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 from docs/:

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

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.