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 run pdm without installing it globally, 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

The current in-tree path is pixi:

pixi run -e docs makedocs

makedocs builds the Sphinx book and writes the sibling doxyYoda C++ API tree to docs/build/html/api-cpp/. The book nav and landing page point at that tree; the Doxygen mainpage points back at the book.

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 live in a .bib file exported from Zotero via better-bibtex.

Local bibliographies, as noted in the documentation, need key prefixes.