Contributing to the Docs on darktable 5.6 user manual

overview

Mon, 01 Jan 0001 00:00:00 +0000

This page defines the style guide for dtdocs and information about how to contribute to the project.

It is included in the user manual so that you can see how the page is rendered as well as how it is written. Please go to GitHub to see the source for this page.

The manual structure and content have been carefully considered based on the following criteria:

The manual should be comprehensive – it should describe all of the functionality available in darktable
It should have a consistent and logical structure and every piece of functionality should have its own logical place within that structure
It should be as long as necessary but as short as possible – brevity is a must
It should be objective
Functionality should be explained once and only once (with the exception of the basic workflow guidelines in the overview section)
Images should be included only where necessary to improve understanding of key principles and should not contain text unless it is unavoidable

We are generally not interested in:

development & deployment

Mon, 01 Jan 0001 00:00:00 +0000

darktable’s documentation is maintained in the dtdocs repository. Changes are introduced through pull requests (see workflow). Translations are maintained through weblate; see translations.

🔗Building

The full set of outputs (HTML site, EPUB, and per-language PDFs) is built by ./tools/build-all.sh <base_url>

This generates the translated content from the PO files, then builds the HTML site, the EPUB, and one PDF per enabled language. Outputs are written under public/, with PDFs at public/<lang>/darktable_user_manual.pdf.

Requirements: Hugo (extended), weasyprint, and po4a for the translation step.

workflow

Mon, 01 Jan 0001 00:00:00 +0000

These instructions assume that you already have a github account and have installed Git as well. Make sure that git is in your PATH by executing the command git in any terminal or cmd and checking that it doesn’t output an error such as “command not found”. If you don’t have git installed, follow these instructions.

🔗Documenting undocumented features

We are particularly interested in documenting closed pull requests that require additions or changes to this manual. Pull requests that require documentation are cataloged with a GitHub label documentation: pending.

styles & conventions

Mon, 01 Jan 0001 00:00:00 +0000

The following details the writing style and documentation conventions used in this manual.

🔗format

This website is authored in pure markdown, using some extensions. It is initially designed to work with the Hugo SSG but intended to be portable enough that it can be easily rendered with another application if required.

Files should be rendered in UTF-8 and should not include any column wrapping.

🔗structure

The following shows the structure of an example main chapter with subsections in the dtdocs website.

translations setup

Mon, 01 Jan 0001 00:00:00 +0000

Translations of darktable’s documentation are maintained via Weblate.

🔗Overview of the setup and flow of information for translations using Weblate

In short:

The docs are primarily maintained in English in the .md files present in content/*.md.
From there a POT file (po/content.pot) of all translatable strings is maintained.
Weblate maintains each language’s individual PO files (po/content.{lang}.po) which contain the translated strings.
Upon deployment of the docs, language-specific .md-files are generated using generate-translations.sh which hugo then renders to .html files and the EPUB and PDF variants.

🔗GitHub to Weblate: source string synchronisation

The original English files (content/*.md) are changed through a pull request on GitHub (see workflow).
A nightly GitHub action updates the POT file (po/content.pot) housing all translatable strings with generate-translations.sh --no-translations. Note: The script updates POT and PO files but we don’t commit the updated PO files to the repository as in our setup the PO files are entirely managed by Weblate to avoid merge conflicts.
Weblate automatically pulls the updated POT file (triggered by the Weblate GitHub app) and internally populates the PO file of each translated language with new/updated strings
Weblate commits the changes to GitHub by opening a pull request.
The pull request gets merged after review.

🔗Weblate to GitHub: translation synchronisation

Translations happen on Weblate. See translators guide for a guide on how to translate.
Weblate internally updates each language’s PO file and commits them to GitHub via pull request. To keep the number of pull requests at bay this happens in batches.

🔗Deployment of translations

Upon deployment at docs.darktable.org translated .md-files are generated from the PO files in /po/ using generate-translations.sh --no-update. This step is disabled for the auto-build GitHub Pages.

translators guide

Mon, 01 Jan 0001 00:00:00 +0000

You are welcome to help translate darktable’s docs. Please read through this guide to learn the conventions and requirements for translation work.

Translations are maintained through Weblate. Unregistered users can add suggestions for translations. To contribute to the translations you need to register with Weblate.

We do not accept automated AI translations without human review and quality control.