MkDocs

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. For more information, please refer to mkdocs documentation.

This package includes the following plugins:

mkdocs-material - Material for MkDocs is a theme for MkDocs, a static site generator geared towards building project documentation.
mkdocstrings - MkDocs plugin to generate API documentation from Python docstrings.
mkdocs-gen-files
mkdocs-literate-nav
mkdocs-section-index

And additional features:

Automatic reference to the source code (docs/gen_reference_pages.py) and imports the associated docstring for each function.
Support for LaTeX equations directly within the code docstring thanks to mathjax.

Local deployment

To deploy the MKDocumentation locally, run the following command:

poetry run mkdocs serve

Github Pages deployment

The MkDocs documentation is automatically generated and published to Github Pages using the github-docs.yml workflow. The workflow is triggered on each push to the main branch and on each release. The workflow will build the documentation and push it to the `gh-pages` branch. Then, a second workflow will be trigered on the `gh-pages` branch focused on the deployment. Once completed, the documentation website is available at https://<USERNAME>.github.io/<REPOSITORY_NAME>/.

NOTE: Prior to deployment make sure you have activated the Github Pages feature (repository > settings > pages) in the repository settings.