Documentation#

This project uses Sphinx to generate documentation from docstrings (documentation in-code) and custom pages written in Markdown (througth the MyST parser).

Build documentation website#

# installer les dépendances additionnelles
python -m pip install -U -r requirements/documentation.txt
# build it
sphinx-build -b html docs docs/_build

Open docs/_build/index.html in a web browser.

Write documentation using live render#

sphinx-autobuild -b html docs/ docs/_build

Open http://localhost:8000 in a web browser to see the HTML render updated when a file is saved.

Add a new page to the documentation#

For example, to add a usage in a new language:

  1. Create a markdown file docs/super_astuces.md

  2. Reference this new page in the homepage toctree of docs/index.html

```{toctree}
---
caption: Table des matières
maxdepth: 3
---
[...les autres pages...]
docs/super_astuces
```

Contribute to an existing/wip translation#

Go on the Weblate translation project page and choose a documentation page to translate.

Add a new translation to the documentation#

Go on the Weblate translation project page and click on “Start a new translation”.

Adapt the docs/_templates/sidebar/navigation.html.ref file by adding the appropriate link in the navigation bar and the appropriate computation in the JavaScript script.

Adapt the docs/multi_lang_build.sh file by adding a language.

For instance, to add a translation us:

Add the line

<li class="toctree-l1"><a id="us-link" class="reference internal" href="#">English (US)</a></li>

in the navigation bar and the line

document.getElementById('us-link').href = "{{prefix}}/us" + newPath;

in the script and the line

sphinx-build -D language=us $1 $2/us

in the construction script.