| 1 |
# Sphinx Documentation Integration |
| 2 |
|
| 3 |
Sphinx is a popular documentation generator in Python community. |
| 4 |
It's commonly used together with services like [Read The Docs](https://readthedocs.org/) |
| 5 |
which automates documentation building, versioning, and hosting for you. |
| 6 |
|
| 7 |
Usually in a pure Python project setting up Sphinx is easy, just follow the |
| 8 |
[quick start](https://www.sphinx-doc.org/en/master/usage/quickstart.html) of |
| 9 |
Sphinx documentation is enough. But it can get complicated when Rust |
| 10 |
based Python extension modules are involved. |
| 11 |
|
| 12 |
With maturin, first you need to make sure you have added a `pyproject.toml` and |
| 13 |
properly configured it to build source distributions, for example a minimal configuration below: |
| 14 |
|
| 15 |
```toml |
| 16 |
[build-system] |
| 17 |
requires = ["maturin>=1.0,<2.0"] |
| 18 |
build-backend = "maturin" |
| 19 |
``` |
| 20 |
|
| 21 |
With this `pip install .` should work when invoked in the project directory. |
| 22 |
|
| 23 |
## Read The Docs Integration |
| 24 |
|
| 25 |
To build documentation on [Read The Docs](https://readthedocs.org/), you need |
| 26 |
to tell it to install the Rust compiler and Python interpreter in its build environment, |
| 27 |
you can do it by adding a `.readthedocs.yaml` in your project root: |
| 28 |
|
| 29 |
```yaml |
| 30 |
# https://docs.readthedocs.io/en/stable/config-file/v2.html#supported-settings |
| 31 |
|
| 32 |
version: 2 |
| 33 |
|
| 34 |
sphinx: |
| 35 |
builder: html |
| 36 |
|
| 37 |
build: |
| 38 |
os: "ubuntu-20.04" |
| 39 |
tools: |
| 40 |
python: "3.9" |
| 41 |
rust: "1.55" |
| 42 |
|
| 43 |
python: |
| 44 |
install: |
| 45 |
- method: pip |
| 46 |
path: . |
| 47 |
``` |
| 48 |
|
| 49 |
If you're using a mixed Rust/Python project layout, make sure you didn't add the |
| 50 |
Python project path to `sys.path` in `conf.py` of Sphinx. Read The Docs |
| 51 |
doesn't install your project in editable mode, adding it to `sys.path` will make |
| 52 |
your project fail to import which breaks documentation generation. |
| 53 |
|
| 54 |
If you need to install a specific version of Sphinx or adding Sphinx |
| 55 |
themes/extensions, you can change the `python.install` section a bit to add an |
| 56 |
extra installation step, for example: |
| 57 |
|
| 58 |
```yaml |
| 59 |
python: |
| 60 |
install: |
| 61 |
- requirements: docs/requirements.txt |
| 62 |
- method: pip |
| 63 |
path: . |
| 64 |
``` |
| 65 |
|
| 66 |
In `docs/requirements.txt` you can add some Python package requirements you |
| 67 |
needs build the documentation. |
| 68 |
|
| 69 |
## Netlify Integration |
| 70 |
|
| 71 |
[Netlify](https://www.netlify.com/) is another popular automated site hosting |
| 72 |
service that can be used with Sphinx and other documentation tools. |
| 73 |
|
| 74 |
Netlify configuration can be specified in a `.netlify.toml` file. Assuming your |
| 75 |
Sphinx documentation files are placed in `docs/` directory, a minimal |
| 76 |
configurationfor maturin based project can be: |
| 77 |
|
| 78 |
```toml |
| 79 |
[build] |
| 80 |
base = "docs" |
| 81 |
publish = "_build/html" |
| 82 |
command = "maturin develop -m ../Cargo.toml && make html" |
| 83 |
``` |
| 84 |
|
| 85 |
You also need to add a `rust-toolchain` file at `docs/rust-toolchain` which netlify |
| 86 |
will use to install the specified Rust toolchain that maturin needs to compile |
| 87 |
your project. |
| 88 |
|
| 89 |
For Sphinx which is written in Python to run you need to add a `runtime.txt` at |
| 90 |
`docs/runtime.txt`, its content should be a Python interpreter version for |
| 91 |
example `3.8`. Then a `requirements.txt` file at `docs/requirements.txt` is |
| 92 |
needed to install Sphinx and its dependencies, you can generate one by: |
| 93 |
|
| 94 |
```bash |
| 95 |
python3 -m venv venv |
| 96 |
source venv/bin/activate |
| 97 |
python3 -m pip install sphinx |
| 98 |
python3 -m pip freeze > docs/requirements.txt |
| 99 |
``` |