Testing

Formatting

Whether the Sphinx documentation is written in valid reStructuredText format can be checked with sphinx-lint. We usually include this in our pre-commit configuration:

.pre-commit-config.yaml
- repo: https://github.com/sphinx-contrib/sphinx-lint
  rev: v0.9.1
  hooks:
    - id: sphinx-lint
      args: [--jobs=1]
      types: [rst]

See also

With Sybil you can not only check reStructuredText, but also Markdown and Myst, for example. Sybil can also check code blocks in the documentation with either pytest or Unittest.

Code formatting

The formatting of code blocks can be checked with blacken-docs, which uses Black. We usually integrate the library via the pre-commit framework:

- repo: https://github.com/adamchainz/blacken-docs
  rev: "v1.12.1"
  hooks:
  - id: blacken-docs
    additional_dependencies:
    - black

blacken-docs currently supports the following black options:

Docstrings coverage

interrogate checks your codebase for missing documentation strings and generates a shields.io-like badge.

You can configure interrogate in the pyproject.toml file, for examle:

pyproject.toml
[project.optional-dependencies]
tests = [
    "coverage[toml]",
    "interrogate",
    "pytest>=6.0",
]

[tool.interrogate]
ignore-init-method = true
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-module = false
ignore-property-decorators = false
fail-under = 95
exclude = ["tests/functional/sample", "setup.py", "docs"]
verbose = 0
omit-covered-files = false
quiet = false
whitelist-regex = []
ignore-regex = []
color = true

See also

You can now insert interrogate into your tox file, for example with

tox.ini
[testenv:doc]
deps = interrogate
skip_install = true
commands =
    interrogate --quiet --fail-under 95 src tests

You can also use interrogate with pre-commit:

.pre-commit-config.yaml
repos:
  - repo: https://github.com/econchick/interrogate
    rev: 1.7.0
    hooks:
      - id: interrogate
        args: [--quiet, --fail-under=95]
        pass_filenames: false

Build errors

You have the option of checking whether your content is built correctly before publishing your changes. Sphinx has a nitpicky mode for this, which can be called up with the -n option, for example with:

$ bin/python -m sphinx -nb html docs/ docs/_build/

C:> Scripts\python -m sphinx -nb html docs\ docs\_build\

Continuous integration

If necessary, you can also check automatically in your CI pipeline whether the documentation is being built and the links are valid. In tox, the configuration can be added as follows:

tox.ini
[testenv:docs]
# Keep base_python in sync with ci.yml and .readthedocs.yaml.
base_python = py312
extras = docs
commands =
  sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html

[testenv:docs-linkcheck]
base_python = {[testenv:docs]base_python}
extras = {[testenv:docs]extras}
commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html

You can then define the following jobs for GitHub, for example:

.github/workflows/ci.yml
docs:
  name: Build docs and run doctests
  needs: build-package
  runs-on: ubuntu-latest
  steps:
  - name: Download pre-built packages
    uses: actions/download-artifact@v4
    with:
      name: Packages
      path: dist
  - run: tar xf dist/*.tar.gz --strip-components=1

  - uses: actions/setup-python@v5
    with:
      # Keep in sync with tox.ini/docs and .readthedocs.yaml
      python-version: "3.12"
      cache: pip
  - run: python -m pip install tox
  - run: python -m tox run -e docs