Maintain this documentation

Three connected references

The user guide explains supported functionality and workflows. The API pages define arguments, defaults, returned data and refusal behavior. The maintainer guide explains code architecture and algorithms. Both use the theory pages for common mathematical terms. Keep detailed kernel descriptions in the maintainer/theory paths rather than requiring an end user to inspect private controllers before making an ordinary request.

Source layout

docs/
  conf.py                 version-bound Sphinx build configuration
  index.rst               navigation and scope
  user/                   tutorials, controls and workflows
  api/                    all top-level exports and return interfaces
  theory/                 mathematical definitions and glossary
  maintainer/             implementation and extension guide
  references.rst          sources
  _static/guide.css        presentation only
  _templates/             fixed-12pt SVG math rendering template
  requirements.txt        documentation build tool requirement

Named Python examples live directly in these sources. They are public tutorial code, not an alternative engine or a physics campaign. Build outputs, test execution and temporary environments are outside this directory. Runtime dependencies remain NumPy and PyYAML; Sphinx is documentation-only.

Build the HTML

Use Python 3.12 and install the development/documentation environment from this repository root:

uv sync --locked --group docs
uv run --no-sync python docs/build.py

Open build/html/index.html. The default build uses MathJax for equations; reading mathematical rendering requires the MathJax assets from its configured CDN. No local LaTeX installation is needed to build this form.

For a completely offline HTML companion, install a LaTeX distribution with amsmath, amssymb and preview, plus dvisvgm, then use:

uv run --no-sync python docs/build.py --svg --output build/html-offline

This renders local SVG equation assets. On Windows the SVG backend passes MiKTeX’s --disable-installer argument; other systems receive no such flag. Adapt that argument if using a different Windows TeX distribution.

The build script treats unresolved references and warnings as errors, imports the installed package for signatures and works from any working directory. For manual Sphinx use:

python -m sphinx -a -n -W --keep-going -b html docs build/html

conf.py binds these contracts to version 0.3.2. Review the documentation before changing that version. Generated HTML stays outside docs/ and src/.

The autodoc hook emits live signatures and selected method names while clearing short source docstrings. Descriptions here are the reviewed contract, avoiding duplicating internal/historical docstrings as if they were the full public manual. Do not use that hook to hide an implementation disagreement: resolve the disagreement or state a genuine support limitation.

Publish on GitHub Pages

The repository’s Package checks workflow builds this manual on Windows and runs the supported package and documentation checks. On a push to main, or a manual workflow dispatch on main, a dependent Ubuntu job downloads the checked HTML artifact and deploys it through GitHub Pages. Pull requests and version-tag pushes do not deploy the site. Deployment permissions are confined to that job; the build/test job retains read-only repository permissions.

One-time setup in the repository: open Settings, Pages, then select GitHub Actions as the publishing source. No Jekyll or Static HTML template is needed; the existing workflow supplies the Sphinx build and deployment. Commit/push the workflow and documentation changes, then check both the Windows check job and the Publish documentation job in Actions. The Pages settings/deployment output shows the resulting URL. The default project URL is https://niornob.github.io/hcphases/; account-level or project custom-domain settings may change that address.

The website follows the checked main branch. Its version heading identifies the currently documented API; it is not a multi-version documentation archive. Release artifacts and tags retain their independent identities.

A dedicated documentation subdomain can be configured later in Pages settings and the domain provider’s DNS. Use a hostname such as hcphases.example.com and a CNAME target of niornob.github.io. The custom domain field takes a hostname, not a URL path. Keep the personal website’s existing hostname/DNS routing when assigning a separate documentation subdomain. For an Actions deployment, GitHub manages the custom-domain setting; a source CNAME file is not required.

Review and distribute

Check all exports against hcphases.__all__, parse and execute the exact named examples, verify internal links and inspect desktop/narrow-screen layouts. Review equations and model/decoder domains against implementation and independent references. Confirm diagram/math/image assets are present locally in the finished build. Preserve a build-tool version inventory and artifact hashes. The local math template uses the standard 12-point article font sizes and avoids an extra anyfontsize dependency. Review that template if changing the configured mathematics font size. The build configuration also normalizes Sphinx 8’s legacy template-path string subclass before Jinja rendering. This shim is scoped to the documentation process; it does not modify the installed dependency or runtime library files.

Distribute the complete HTML tree, not just index.html. It contains navigation, search scripts, CSS and equation assets. A zipped documentation bundle can be extracted and opened locally or served by any ordinary static HTTP server. No server-side application or scientific runtime is needed to read it.

This documentation companion is separate from the already built runtime wheel. Its release/version describes the API documented; the archive hash identifies the particular documentation build. A later engine release must update the support matrix, examples and algorithm descriptions together.