# Writing documentation

All of the team's repositories are documented using the [Sphinx] documentation engine.
This page contains resources to help you understand [Sphinx] and the configurations we commonly use in our repositories.

[Sphinx]: https://sphinx-doc.org

## MyST Markdown

Our repositories use [MyST Markdown](https://myst-parser.readthedocs.io).
This is enabled via the [`myst-parser` Sphinx extension](https://myst-parser.readthedocs.io).

## Build documentation locally

There are a few ways to build the documentation in our repositories.
Some depend on certain tools being installed.
Here are a few common ways to do so, from most- to least-automated.

### Building with `nox`

We use [the `nox` command line tool](https://nox.thea.codes/en/stable/) to automate the build documentation locally.
`nox` is a tool for quickly running commands in an isolated build environment.
It is similar to `Make`, but with a Python configuration and with local build environments that are isolated to each job that you run.

`nox` is configured with [a file called `noxfile.py`](https://nox.thea.codes/en/stable/config.html).

**To install `nox`**, follow the [steps in Nox's documentation](https://nox.thea.codes/en/stable/tutorial.html#installation).

**To see a list of available commands**, run

```bash
nox -l
```

**To install the requirements for documentation, build them locally, and have a live preview**, run

```bash
nox -s docs -- live
```

``````{note}
If you don't want the live preview, run

```bash
nox -s docs
```

This will place the built HTML files in `docs/_build/html` for you to inspect as you wish.
``````

(docs:build-make)=
### Building with `Makefile`s

Many of our repositories also have a `Makefile` that runs commands in your currently-active Python environment.

To do so, follow these steps:

1. Install the requirements for the documentation. This is often in a `docs/requirements.txt` file.
   Assuming a file in this location, run

   ```bash
   pip install -r docs/requirements.txt
   ```
2. Look for a `Makefile` in the `docs` repository.
   This is auto-generated by [Sphinx] to help you build the documentation.
   To build the `html` for our documentation, run

   ```bash
   make -C docs html
   ```

   It will put the built documentation in `_build/html` (depending on our configuration this may change a bit).

### Building with `sphinx-build`

This is the way to have the most control over a documentation's build, but is also the most cumbersome to do repetively.

To do so, install the documentation requirements (see [](docs:build-make) and run a command like so:

```bash
sphinx-build docs docs/_build/html
```

See [the `sphinx-build` documentation](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) for more information.