Development workflow#

The most common maintenance tasks, in roughly the order you hit them.

Build the documentation#

make docs        # HTML, with warnings as errors
make docs-open   # build and open in a browser
make lens        # this project's own Sphinx Lens index

make lens is worth running on any documentation change: this repository is one of the corpora in Real-world corpora, so its own index is the fastest way to notice an extraction regression.

Use the pinned Python#

The generated .python-version records the exact Python interpreter that ran Copier. uv uses this file automatically, and template updates preserve it.

Run local QA before pushing#

make qa
make test

If prek is not installed, install it once with:

uv tool install prek

Update dependencies safely#

This template uses uv groups and cooldown windows. After dependency changes:

uv sync
make qa
make test

Publish a release#

make bump
make release

Release workflows publish package artifacts and canonical docs.

Verify release attestations#

Each wheel and source distribution has a PEP 740 publish attestation signed through Sigstore and uploaded to PyPI with the package.

Verify a published artifact by passing its PyPI file URL:

uvx pypi-attestations verify pypi \
  --repository https://github.com/mgaitan/sphinx-lens \
  https://files.pythonhosted.org/path/to/distribution.whl

Preview documentation in pull requests#

When docs files change in a PR, CI deploys a preview to:

https://mgaitan.github.io/sphinx-lens/_preview/pr-<PR_NUMBER>/

If needed, dispatch docs publishing manually:

gh workflow run cd.yml --ref main

gh authentication can use GH_TOKEN.

Development workflow

Contents