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 --------------- .. code-block:: text 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: .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console 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.