Debian Codegraph @

guide/src/sphinx.md

raw
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 ```