Building and editing the docs#

Run commands from the repository root in your activated Python environment. The dev extra already includes the documentation tools. For a docs-only setup, install:

python -m pip install -e ".[docs]"

Build and preview#

Build the HTML site with warnings treated as errors:

python -m sphinx -b html -W docs docs/_build/html

Open docs/_build/html/index.html in a browser. Check the changed pages, code examples, tables, cross-references, and sidebar navigation. The build checks Sphinx references and syntax but does not execute documented examples.

For a local HTTP preview, run:

python -m http.server 8000 --bind 127.0.0.1 --directory docs/_build/html

Open http://127.0.0.1:8000 and stop the server with Ctrl+C when finished. If you prefer Make, make -C docs html SPHINXOPTS="-W" builds the same output.

Rebuild from scratch#

After changing navigation or moving pages, clean the generated output and rebuild every page so sidebars do not mix old and new structures:

python -m sphinx -M clean docs docs/_build
python -m sphinx -b html -E -a -W docs docs/_build/html

The clean step removes generated build files. -E discards Sphinx’s saved environment and -a writes every page. Refresh the browser after rebuilding; use a hard refresh if it still displays older content.

Choose where to edit#

  • docs/user/ explains how to use the GUI and Python API.

  • docs/examples/ contains worked configurations and examples.

  • docs/developer/ describes contributor and maintainer tasks.

  • docs/ibsi/ explains validation coverage and reference limitations.

  • docs/reference/ organizes the API reference with autosummary entries. API descriptions and parameter details come from docstrings in zrad/.

Update the user guide when behavior changes, docstrings and reference entries when public APIs change, and examples when a new workflow needs illustration. Add troubleshooting guidance for common user-facing failures. Explain when to use a feature before listing its parameters.

Add a new narrative page as an .rst file and include its name, without the extension, in the relevant parent page’s toctree. For example, the GUI pages are listed in docs/user/gui_workflows.rst. Use :doc: for links to pages and explicit labels with :ref: for sections that other pages need to reference. Preserve existing labels when moving content.

For a new public class, add its autosummary entry to the appropriate reference page and document the class in its source docstring. Sphinx generates reference stubs under docs/reference/generated/; edit the source entries and docstrings rather than generated stubs or HTML in docs/_build/.

Fix build problems#

  • Sphinx or an extension is missing: activate the intended environment and install .[docs] there. Use python -m sphinx to use that interpreter.

  • An autodoc import fails: install Z-Rad and its dependencies in the same environment, then inspect the import exception in the build output.

  • A page or section cannot be found: check its toctree entry, link, and label. Update links after renaming pages or moving sections.

  • Sidebars or deleted pages remain visible: perform the clean rebuild above and confirm the browser is showing this build’s output.

  • The displayed version is unexpected: check zrad.__version__ in zrad/__init__.py and rebuild. Sphinx and package metadata both read this value; change it only when intentionally updating the project version.

The documentation workflow runs on pushes to master and manual dispatch, not on pull requests. Build documentation changes locally before review; see Continuous integration for deployment details.