Documentation Maintenance#

The hosted manual is built directly from docs/ and deployed by the GitLab Pages job. Product pages use MyST Markdown or reStructuredText; generated build output is not source.

Install Documentation Dependencies#

Use a dedicated environment or virtual environment so the versions in docs/requirements.txt are tested exactly:

python -m venv /tmp/mppt-docs-venv
/tmp/mppt-docs-venv/bin/python -m pip install \
  --requirement docs/requirements.txt

Build Locally#

From the repository root:

rm -rf docs/_build/html docs/_build/doctrees
/tmp/mppt-docs-venv/bin/sphinx-build \
  -W --keep-going -d docs/_build/doctrees -b html docs docs/_build/html

Or activate the dedicated environment and run the Makefile from the repository root:

source /tmp/mppt-docs-venv/bin/activate
make -C docs html

Both commands place doctrees beside the HTML directory rather than inside it. The Makefile also removes the previous HTML and doctree output before building, so deleted pages cannot survive in an incremental site.

Warnings are errors. A page must be reachable from the primary toctree unless it is explicitly excluded from Sphinx input.

Run the link checker separately:

make -C docs linkcheck

External publisher sites may reject automated clients. Record a confirmed publisher-side denial separately; do not hide broken internal links or invalid URLs behind a broad ignore rule.

Header Navigation#

  • The first five root toctree entries form the header: Quick Start, Installation, Workflow, YAML Input and Results. Keep these labels short.

  • Additional pages appear in More. Put Caspy, releases, troubleshooting and environment setup before specialist guides.

  • When shortening a page title, retain its filename and the old title anchor.

Homepage#

index.rst owns the root toctrees and includes _includes/homepage.html for the Mineral landing page. The homepage uses the same PyData header, More menu, mobile navigation and search as the manual. Its toctrees are hidden in the body but remain the source for navigation.

_static/homepage.css scopes the neutral palette and wide layout to the homepage. _static/homepage.js enhances the stage tabs, command-copy button and Roadmap drawer. The scientific illustrations and bra/ket MathML are embedded in the HTML; there are no external drawing or font dependencies.

The floating Roadmap button distinguishes available selected DF CVCV streaming and native magnetic response from further diagram acceleration, MPPT-energy-guided selection and energy gradients. Update these statuses when capabilities ship; each available feature links to or is described by its owning reference page.

The drawer supports Close, Escape and backdrop dismissal, restores keyboard focus, and respects reduced-motion preferences. Without JavaScript, the same content appears inline above the footer.

Keep the original ASCII text identical to diagpt/io_manager.f90. Particle/hole indices and arrowheads use a separate SVG overlay. The bra and ket use independent state and determinant indices; the method figure adds a second-order correction to the model-space matrix. Its notation is explained in the diagrammatic formulation.

Orbital generation has its own feature inside the capabilities section. Its compact target-character expansions illustrate a rotation within the same MO space. Keep the projection procedure and input controls in the orbital-generation guide.

The quick start includes _static/quickstart/ce.yaml directly, so the displayed full input and its download stay identical. Keep the companion basis/ECP file with the YAML. Its source is the Ce HF workflow regression case under test_suite/workflows/yaml/hf/Ce3+_nosym_soc_with_g_h/.

Homepage release highlights#

Maintain short release benefits in releases/highlights.yaml. The homepage shows all stable patches in the current minor line and the preceding available minor line, including their .0 releases. For v0.3.0 this means v0.3.0, v0.2.2, v0.2.1 and v0.2.0. At v0.4.0 the v0.2.x line leaves the panel; the complete notes remain available through Releases. Major transitions use the preceding available major/minor pair rather than arithmetic on the minor number.

Each stable release needs one catalog entry with version, status and one to five highlights. Each highlight has plain-text component and text fields. Use short benefits; detailed usage and migration belong in releases/vX.Y.Z.md. Keep older entries in the catalog. Mark shipped entries released, the next release upcoming, and set preview to the intended source-tree preview version.

The installed mppt-docs Sphinx extension under _ext/ renders the panel at build time. A sanitized snapshot’s release-manifest.json supplies the publication ceiling and authorizes its exact tag, even while the source catalog says upcoming. Source builds use preview and visibly label upcoming content. A source preview can use -D mppt_release_tag=v0.2.2; it cannot override a snapshot’s identity. RC builds show earlier stable news. Missing summaries, duplicate versions, missing notes or missing minor bases fail the documentation build.

The panel starts open. Desktop uses a sticky left column; smaller screens use an inline block with bounded scrolling. Native disclosure controls remain usable without JavaScript. JavaScript remembers closure for the browser session and reopens the panel when the displayed version set changes. Escape closes the focused panel and returns focus to its summary. Storage denial leaves the controls functional, and reduced-motion preferences disable layout animation.

Install documentation requirements from the repository root so the local ./docs/_ext dependency resolves. For extension checks, install python -m pip install -e 'docs/_ext[test]', then run python -m pytest -q docs/_ext/tests. Its Ruff configuration preserves the recorded global baseline, adds annotation/absolute-import checks and targets Python 3.11. Source CI uses the same config and pinned Ruff/Pyright versions.

Information Architecture#

  • README.md provides the shortest supported path and links here for details.

  • Getting-started pages own installation, first run, and troubleshooting.

  • Workflow pages own YAML, CLI, HDF5, restart, and output contracts.

  • Component references own specialized or manual behavior.

Do not put implementation plans, review backlogs, raw machine worklogs, or superseded migrations in hosted product documentation. A curated benchmark page may retain durable guidance when it records hardware, revision, methodology, and whether each value was measured or estimated. Keep detailed worklogs in non-published development records and remove obsolete product guidance.

Published Output#

Copied source pages and source links are disabled. The Pages job builds into a clean public/ directory, keeps doctrees outside the artifact, and publishes only rendered site files.

In GitLab CI, CI_PROJECT_URL and CI_PAGES_URL select the repository icon and canonical site URL for the project running the build. Local release-oriented defaults can be overridden with MPPT_DOCS_REPOSITORY_URL and MPPT_DOCS_PAGES_URL when testing another deployment context.

Change Checklist#

  1. Update every page that owns changed public behavior or a changed data contract.

  2. Update README only when the concise onboarding path changes.

  3. Add new pages to docs/index.rst; remove links before deleting a page.

  4. Search for references to renamed settings, datasets, commands, and files.

  5. Build HTML with warnings as errors.

  6. Run linkcheck and distinguish internal failures from external-site policy.

  7. Keep docs/_build, its doctrees, _doxygen, and generated API output out of commits and published artifacts.

The GitLab Pages job installs docs/requirements.txt, runs the strict HTML build, and publishes the clean public/ artifact on the default branch.