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

Note

uvx simplifies running Python commands, and pdm handles version updates better, syncing nicely with the pyproject.toml so no Python dependencies not needed by the client should be in the environment.yml

# 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.

Docs CI installs eonclient into the docs-mta prefix, then runs scripts/regen_tutorial_figures.py. That step minimizes docs/lj13.con with [Debug] write_movies = true and writes plt-min profile and landscape PNGs to docs/source/fig/generated/ (gitignored). The docs pixi feature supplies rgpycrumbs, chemparseplot, and ira. A missing figure fails the docs job. The same script can be run locally once eonclient is on PATH.

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.