Maintaining the manual

The manual uses Sphinx, MyST Markdown, numpydoc and sphinx-gallery. Its five entrance sections are defined by docs/index.md; each section owns a nested toctree. Keep each authored page in one navigation location and cross-reference it from other chapters. Enable readers to follow the user guide in order and to enter at a specific model or property.

Build and examples

uv run poe docs

The output is docs/_build/html/. Warnings and missing references fail the build. The gallery runs Python scripts from docs/gallery/ and writes generated pages and figures under docs/auto_gallery/. Edit the scripts and their narratives, not the generated pages. API pages are generated from the overview in docs/api/index.md and the package docstrings.

Runnable Markdown examples are checked by tests/test_docs_snippets.py; installation and propagation examples are also exercised by the clean-install release tests. When splitting a page, give its examples their own imports and setup and add it to the snippet test’s page list. Retain old document URLs and fragment identifiers as overviews or links when moving material.

Numerical tables

The accuracy and validation pages contain marked tables with freshness assertions in tests/test_*page.py and tests/solid/test_*page.py. Keep their start/end markers when moving a table and update the test and its generator together. Regenerate tables from stored results; do not edit numbers to match a narrative.

The third-order support tables are regenerated with:

uv run python tools/fit/nonlinear_support.py --update-docs

Removed public comparison tables are retained in tests/data/historical_documentation_tables.md, with their numerical tests. Ionisation and Raman table tests search the relevant split chapters; the two-photon and third-order support generators update their marked destination pages directly.

Other table generators and their target pages are identified by their marker names in the documentation tests and tools/. A change in a scientific conclusion belongs in the register with its evidence. Removing an obsolete public comparison does not justify removing meaningful regression coverage.

Source catalogue

docs/_ext/source_catalogue.py reads every TOML record in src/optmat/data/sources/ before Sphinx discovers documents. It writes an alphabetical index and one stable page per source identifier under docs/generated/sources/. Those files are ignored by Git, and unchanged pages are not rewritten. Deleted source records lose their generated page at the next build.

Edit the source record to correct its metadata, following the data and register rules. Do not edit the generated catalogue. Notes, formula-only and notes-only records, missing DOIs, Unicode and punctuation are supported without a second bibliography or new schema. The catalogue reports recorded content; it does not decide which datasets are scientifically suitable for a fit.

Reviewing changes

Check the rendered page, equations, tables and figures as well as the source diff. Test both the sequential reading route and direct links from the introduction, API and gallery. Run the focused documentation tests and the full Development checks gate, and report any unavailable primary-source or numerical verification.