Sphinx Documentation Integration

Sphinx is a popular documentation generator in Python community. It's commonly used together with services like Read The Docs which automates documentation building, versioning, and hosting for you.

Usually in a pure Python project setting up Sphinx is easy, just follow the quick start of Sphinx documentation is enough. But it can get complicated when Rust based Python extension modules are involved.

With maturin, first you need to make sure you have added a pyproject.toml and properly configured it to build source distributions, for example a minimal configuration below:

[build-system]
requires = ["maturin>=1.0,<2.0"]
build-backend = "maturin"

With this pip install . should work when invoked in the project directory.

Read The Docs Integration

To build documentation on Read The Docs, you need to tell it to install the Rust compiler and Python interpreter in its build environment, you can do it by adding a .readthedocs.yaml in your project root:

# https://docs.readthedocs.io/en/stable/config-file/v2.html#supported-settings

version: 2

sphinx:
  builder: html

build:
  os: "ubuntu-20.04"
  tools:
    python: "3.9"
    rust: "1.55"

python:
  install:
    - method: pip
      path: .

If you're using a mixed Rust/Python project layout, make sure you didn't add the Python project path to sys.path in conf.py of Sphinx. Read The Docs doesn't install your project in editable mode, adding it to sys.path will make your project fail to import which breaks documentation generation.

If you need to install a specific version of Sphinx or adding Sphinx themes/extensions, you can change the python.install section a bit to add an extra installation step, for example:

python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .

In docs/requirements.txt you can add some Python package requirements you needs build the documentation.

Netlify Integration

Netlify is another popular automated site hosting service that can be used with Sphinx and other documentation tools.

Netlify configuration can be specified in a .netlify.toml file. Assuming your Sphinx documentation files are placed in docs/ directory, a minimal configurationfor maturin based project can be:

[build]
  base = "docs"
  publish = "_build/html"
  command = "maturin develop -m ../Cargo.toml && make html"

You also need to add a rust-toolchain file at docs/rust-toolchain which netlify will use to install the specified Rust toolchain that maturin needs to compile your project.

For Sphinx which is written in Python to run you need to add a runtime.txt at docs/runtime.txt, its content should be a Python interpreter version for example 3.8. Then a requirements.txt file at docs/requirements.txt is needed to install Sphinx and its dependencies, you can generate one by:

python3 -m venv venv
source venv/bin/activate
python3 -m pip install sphinx
python3 -m pip freeze > docs/requirements.txt