Development guide#

This page provides procedures and guidelines for developing and contributing to Documenteer.

Scope of contributions#

Documenteer is an open source package, meaning that you can contribute to Documenteer itself, or fork Documenteer for your own purposes.

Since Documenteer is intended for internal use by Rubin Observatory, community contributions can only be accepted if they align with the Rubin Observatory’s aims. For that reason, it’s a good idea to propose changes with a new GitHub issue before investing time in making a pull request.

Documenteer is developed by the SQuaRE team. The lead developer and maintainer is Jonathan Sick.

Environment set up#

To develop Documenteer, clone or fork the repository and install it with uv:

git clone https://github.com/lsst-sqre/documenteer.git
cd documenteer
make init

The canonical Python version for development is declared in the .python-version file at the root of the repository. uv reads that file, so make init (uv sync) and uv run furnish that interpreter automatically, and the GitHub Actions workflows use the same file to pick the Python for their lint and docs jobs. Documenteer supports a wider range of Python versions than that (see requires-python and the classifiers in pyproject.toml); the full set is exercised by the nox test matrix described below.

A complete environment also needs the compiled web assets (see Handling CSS, JavaScript, and image assets). Because the asset build pulls the private @lsst-sqre/rubin-style-dictionary package from GitHub Packages, you must first authenticate npm to GitHub Packages with a classic read:packages personal access token.

Code formatting and linting with prek#

Documenteer uses prek (a drop-in, config-compatible replacement for pre-commit) to automatically and consistently format and lint the codebase on each commit. By running make init, prek is already installed in your environment.

If prek “fails” because the black or isort code formatters changed the source, simply git add the changes and try the commit again.

To learn more about the hook configuration, see the .pre-commit-config.yaml file in the repository (prek reads the same configuration format as pre-commit).

Running tests via nox#

Development tasks are run through nox (via nox-uv), which is provisioned by the make init command. Run nox through uv so the runner and its environments are managed for you:

uv run --only-group=nox nox

Running nox with no arguments runs a lean default set: lint, typing and the Sphinx 8 and 9 test runs on the canonical development Python (from .python-version), and a docs build. The available sessions are:

nox sessions#
Session	Description
`test`	Run the test suite with pytest. Parametrized over Python (`3.12` through `3.15`) and Sphinx versions (`8`, `9`, `dev`). Coverage is opt-in (see below).
`typing`	Run mypy (type annotations checker). Parametrized over Python (`3.12` through `3.15`) and Sphinx versions (`8`, `9`, `dev`).
`lint`	Run the prek hooks (including the prettier web-asset hook).
`coverage-report`	Aggregate unit test coverage reports from the `test` sessions and display a report. Runs automatically after the `test` sessions when `DOCUMENTEER_COVERAGE` is set (unless `DOCUMENTEER_COVERAGE_NO_COMBINE` is also set).
`docs` / `docs-linkcheck`	Build the documentation and check its links.
`demo`	Build the demo technote projects as an end-to-end smoke test. Parametrized over Python (`3.12` through `3.15`) and Sphinx versions (`8`, `9`, `dev`).
`packaging`	Build the PyPI package and check it with twine.
`vale`	Lint the documentation prose with Vale (advisory; not in the default set and never blocks). See Editorial linting with Vale.

By default the test session runs without coverage instrumentation. To collect coverage and print a combined report across the test sessions, set DOCUMENTEER_COVERAGE, e.g. DOCUMENTEER_COVERAGE=1 uv run --only-group=nox nox -s test. In CI each matrix cell additionally sets DOCUMENTEER_COVERAGE_NO_COMBINE so it skips the per-invocation combine and uploads its raw .coverage.* data; a central coverage-combine job then merges coverage once across the whole Python × Sphinx matrix.

It is also possible to run individual sessions, for example:

uv run --only-group=nox nox -s lint

The test, typing, and demo sessions are parametrized over both Python and Sphinx versions, so their session IDs carry both factors. uv furnishes the requested interpreter on demand. Select a specific cell with the full session ID, for example to type-check against Python 3.13 and Sphinx 8:

uv run --only-group=nox nox -s "typing-3.13(sphinx='8')"

Run the full Python × Sphinx grid for a session by naming it without a parameter, for example all the test cells:

uv run --only-group=nox nox -s test

To learn more about the available sessions, run nox -l or review the noxfile.py file in the code repository.

Running tests through pytest#

Although nox is the recommended method for running tests, it is still possible to run tests directly through pytest:

pytest

This is particularly useful for running a single test module (provide the test module’s path as an argument to the pytest command).

Building documentation#

Documentation is built with Sphinx:

uv run --only-group=nox nox -s docs

The HTML output is located in the docs/_build/html directory.

To check links:

uv run --only-group=nox nox -s docs-linkcheck

For advisory editorial feedback on the prose, run Vale (see Editorial linting with Vale):

uv run --only-group=nox nox -s vale

Updating the change log#

Each pull request should update the change log (CHANGELOG.rst). Add a description of new features and fixes as list items under a section at the top of the change log called “Unreleased:”

Unreleased
----------

- Description of the feature or fix.

If the next version is known (because Documenteer’s master branch is being prepared for a new major or minor version), the section may contain that version information:

X.Y.0 (unreleased)
------------------

- Description of the feature or fix.

If the exact version and release date is known (because a release is being prepared), the section header is formatted as:

X.Y.0 (YYYY-MM-DD)
------------------

- Description of the feature or fix.

Style guide#

Code#

Code formatting is performed automatically through black and isort. Generally this means that the code base automatically conforms to PEP 8 and will pass the flake8 linter.
Write tests for Pytest.
Use PEP 484 type annotations wherever possible, especially for new code.
Use Click for command-line interfaces.

Documentation#

Follow the LSST DM User Documentation Style Guide, which is primarily based on the Google Developer Style Guide.
Document the Python API with numpydoc-formatted docstrings. See the LSST DM Docstring Style Guide.
Follow the LSST DM ReStructuredTextStyle Guide. In particular, ensure that prose is written one-sentence-per-line for better Git diffs.