Sphinx Documentation Workflow#

PyUnitWizard documentation is built with Sphinx + MyST + myst-nb.

Local build#

make -C docs html

The generated site is written to docs/_build/. Open docs/_build/index.html. The alternative command sphinx-build -M html docs docs/_build writes to docs/_build/html/, as used by the hosted action; clean stale autosummary stubs first with python docs/clean_api.py when using that command directly.

Publication#

The documentation workflow runs on stable GitHub Releases and manual dispatch; pushing main alone does not publish the site. Authorized maintainers can run:

gh workflow run sphinx_docs_to_gh_pages.yaml --repo uibcdf/pyunitwizard --ref main

Check the exact source commit, successful deployment and updated served pages. See the documentation contributor guide for environment setup, output layouts and publication verification.

Contribution expectations#

When you update behavior or public contracts:

  • update the relevant User and/or Developer pages,

  • ensure links and toctrees remain valid,

  • keep narrative structure explicit (guided, not fragmentary).

Common pitfalls#

  • orphan pages not included in any toctree,

  • stale examples that no longer match runtime behavior,

  • notebook content copied from unrelated projects.

Run documentation build locally before opening a PR.