# Writing documentation

All of the team's repositories are documented using [the Sphinx documentation engine](https://sphinx-doc.org).
This page contains resources to help you understand Sphinx and the configurations we commonly use in our repositories.

## MyST Markdown

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

## reStructuredText

The default markup language used by Sphinx is [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/).
It is a rich and extensible way to write content for our documentation.
See [the Sphinx reStructuredText documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/) for an in-depth guide of how to use it.

## 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 often use [the `nox` command line tool](https://nox.thea.codes/en/stable/) to 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`**, run this command:

```bash
pip install nox
```

**To see a list of available commands**, run this command:

```bash
nox -l
```

For example, we often name our documentation command `docs`.
**To install the requirements for documentation and build them locally**, run:

```
nox -s docs
```

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

We often add an extra parameter to instead run a live server via [the `sphinx-autobuild` extension](https://github.com/executablebooks/sphinx-autobuild).
**To build docs with a live serve that auto-reloads as you change things**, run this command:

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

Note that this will **only work for repositories that have a `noxfile.py` added**.

(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 this command:

   ```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 this command:

   ```bash
   cd docs
   make 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.