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:

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