Build and publish the docs

From a Podbench checkout:

uv run --locked tox -e docs

This builds Sphinx with warnings treated as errors. Open build/html/index.html to review the output. For a browser preview that reloads when files change:

uv run --locked tox -e docs-autobuild

Follow the local URL printed by the command. Edit Markdown pages in docs/ and add them to the appropriate table of contents. Keep tutorials focused on a complete task and put optional operations in how-to guides.

If the preview reports address already in use, another server is using its port. Stop the previous preview with Ctrl+C in its terminal, or choose another port:

uv run --locked tox -e docs-autobuild -- --port 8001

This error concerns the preview server; the preceding Sphinx build may have completed successfully.

The project uses the Diamond Light Source Python Copier template, pinned in .copier-answers.yml with docs_type: sphinx. The Sphinx conversion was generated with:

uvx copier update --defaults --trust --vcs-ref 5.4.0 --data docs_type=sphinx

The template supplies MyST Markdown, the PyData theme, tox build/preview commands and the versioned GitHub Pages workflow. Podbench keeps concise task guides in place of the template’s sample API and contributor pages.

Pull requests build a downloadable docs artifact. Builds on main and tags publish versioned documentation to gh-pages. After the first successful publish, set the repository’s Settings → Pages source to Deploy from a branch, branch gh-pages, directory / (root). The entry page redirects to main. The periodic workflow checks external links weekly; run it locally with:

uv run --locked tox -e docs -- -b linkcheck