Working with the documentation

eOn is a relatively complex project, with both C++ and Python sources, along with a large set of options.

Setup

Although we use micromamba for handling system dependencies, the documenation is handled via the python ecosystem. Namely:

To facilitate interactions with pdm, uvx is recommended.

Building locally

# Setup dependencies
uvx pdm sync
# Need to install for autodoc-pydantic
uvx pdm run pip install . -vvv
uvx pdm run sphinx-build -b html docs/source docs/build/html

This can be viewed locally with an HTTP server.

python -m http.server docs/build/html

Writing documentation

We use myst markdown via the myst-parser extension for almost everything, however, the pydantic schema is handled by autodoc-pydantic which requires rst directives only, so:

  • The docstrings for the configuration are formatted with rst.

  • eval-rst is required to wrap the configuration stanzas in the myst markdown files

Additions

The following sections detail methods to add functionality to the documentation.

Adding extensions

Additions to the build process are handled by the pdm development group docs, so additions are done via:

uvx pdm add -dG docs "sphinxcontrib-bibtex"

Adding citations

Citations are handled in a .bib file which is exported via better-bibtex with Zotero. Kindly do not modify these by hand.

Note that because we need local bibliographies, as noted in the documentation we need to use key prefixes.