Documentation

The documentation is built with Sphinx. Custom pages are written in Markdown via the MyST parser; the API reference is generated from the in-code docstrings.

Stack

  • Sphinx with the Read the Docs theme.

  • MyST for the Markdown pages under docs/usage/ and docs/development/, with extensions such as colon_fence, linkify and substitution enabled in docs/conf.py.

  • autodoc + autosummary + sphinx-autodoc-typehints render the API reference from docstrings into docs/api/generated/.

  • sphinx-copybutton adds copy buttons to code blocks.

Project identity (title, version, author, icon) is read from stratified_packager/metadata.txt through stratified_packager/__about__.py, and the changelog is parsed from CHANGELOG.md. The build dependencies live in the doc group of pyproject.toml.

Build

just build-docs            # HTML (default)
just build-docs latexpdf   # PDF via LaTeX

The HTML lands in docs/_build/html/; open docs/_build/html/index.html. The build is strict: it runs with -W --keep-going and conf.py enables nitpicky mode, so warnings — including unresolved cross-references — are collected and then fail the build. Fix them rather than suppressing them.

Preview locally

Serve the built HTML and open it in a browser:

just serve-docs  [PORT]   # http.server on docs/_build/html (default port 8000)
just browse-docs [PORT]   # open http://localhost:PORT

For an iterative workflow, use live reload instead:

just autobuild-docs [PORT]   # build + serve + watch + open browser (default port 8000)

sphinx-autobuild builds the docs, serves them at http://localhost:PORT, opens your browser, and rebuilds and reloads the page whenever a file under docs/ or stratified_packager/ changes. Unlike build-docs it runs without -W, so in-progress warnings don’t block the preview — re-run just build-docs for the strict, CI-equivalent check.

Adding a page

Create a Markdown file under docs/ and register it in a toctree in docs/index.md (the master document). Then rebuild.

Cleaning

just clean removes the generated output, including docs/_build and the autosummary stubs under docs/api/generated.

Continuous deployment

The documentation.yml GitHub Actions workflow builds the docs with the same strict flags and deploys them to GitHub Pages on every push to main and on tags. The Pages site also serves the plugin’s plugins.xml, so it doubles as the QGIS plugin repository.