Documentation

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

Build documentation website

To build it:

# install aditionnal dependencies
python -m pip install -U -r requirements/documentation.txt
# build it
sphinx-build -b html docs docs/_build
# optimized (quiet, multiprocessing, doctrees separated)
sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html

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

Write documentation using live render

sphinx-autobuild -b html -d docs/_build/cache 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 into docs/{locale}/usage/my_new_page.md where {locale} is the language code (en, fr, it, sp…)

  2. Reference this new page in the homepage toctree (index.md) of the language:

```{toctree}
---
caption: How to use the plugin
maxdepth: 1
---
usage/index
usage/my_new_page
```

Bibliography

References are managed with the bibtex extension for Sphinx and stored in the docs/_static/bibliography/thyrsis.bib file.

To add a new reference:

  1. Update the file

  2. Use the syntax to add a new reference:

    {cite}`gerke-genuchten:1993`