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
properly configured it to build source distributions, for example a minimal configuration below:
requires = ["maturin>=1.0,<2.0"]
build-backend = "maturin"
pip install . should work when invoked in the project directory.
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:
- method: pip
If you're using a mixed Rust/Python project layout, make sure you didn't add the
Python project path to
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:
- requirements: docs/requirements.txt
- method: pip
docs/requirements.txt you can add some Python package requirements you
needs build the documentation.
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:
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
For Sphinx which is written in Python to run you need to add a
docs/runtime.txt, its content should be a Python interpreter version for
3.8. Then a
requirements.txt file at
needed to install Sphinx and its dependencies, you can generate one by:
python3 -m venv venv
python3 -m pip install sphinx
python3 -m pip freeze > docs/requirements.txt