Documentation¶

This documentation lives in docs/ and is built with Zensical.

make docs-serve        # live preview on http://localhost:8000
make docs-test         # markdown lint, strict build and link check with a summary
make docs-screenshots  # regenerate the screenshots with Playwright
make docs-po           # update docs/locales/*.po after changing English pages
make docs-l10n         # build content-<lang>/ from the PO files (docs-build does it too)
make docs-serve DOCS_LANG=de   # preview a translation after docs-l10n

All tools run in Docker (python:3-slim for Zensical, davidanson/markdownlint-cli2, lycheeverse/lychee), so Docker is the only requirement. The changelog page includes CHANGELOG.md from the repository root, so it never needs to be copied.

Screenshots use invented people and clubs only. Update the documentation together with the feature it describes.

Translations¶

The English pages are the source. po4a splits them into paragraphs, headings, list items and table blocks in docs/locales/docs.pot; the translations live in docs/locales/{de,fr,it}.po, the same gettext format as the app's catalogs. The pages of Home, My training, User guide and Reference are translated; the admin guide, the developer pages and the changelog stay English.

• After changing an English page, run make docs-po. Changed paragraphs become untranslated (or fuzzy) in the PO files; translate them there.
• A page is only published in a language when at least 80 % of it is translated; otherwise that language shows the English page, so a half-finished translation never appears.
• Keep Markdown, links, {#anchor} ids, ++key++ shortcuts and code in a translation as they are. Headings that other pages link to carry an explicit {#id}, so links keep working when the heading text is translated.
• Bold UI labels must match the app's own translations in web/src/locales/*.po.
• Navigation labels and a few theme texts are translated in LABELS in docs/l10n.py.

The build (locally make docs-build, in CI the job docs-build) runs l10n.py, which needs po4a, then builds the English site into site/ and each language into site/<lang>/. The language switcher in the header links the four sites. Screenshots are shared and show the English interface.