# Sphinx Documentation Integration

Sphinx is a popular documentation generator in Python community.
It's commonly used together with services like [Read The Docs](https://readthedocs.org/)
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](https://www.sphinx-doc.org/en/master/usage/quickstart.html) 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:

```toml
[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](https://readthedocs.org/), 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:

```yaml
# 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:

```yaml
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](https://www.netlify.com/) 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:

```toml
[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:

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