Writing documentation

Build the documentation

Scientific Python software documentation can be written in the Markdown syntax, which looks like this:

# My nifty title

- list
- of
- items

Some **bold** or _italicized_ text!

```python
# A code block

1 + 1
```

This documentation “source code” is then built into a formats like HTML or PDF to be displayed to the user.

There are a variety of tools that can do this. In this guide we will present an approach that is mainstream in the scientific Python community: the Sphinx documentation generator with the MyST plugin. Refer to the MyST documentation for more information on the Markdown syntax in general and MyST’s flavor of Markdown in particular.

We’ll start with a very basic template. Start by create a docs/ directory within your project (i.e. next to src/).

mkdir docs

In this directory, we will create a minimal Sphinx configuration file at docs/conf.py.

# content of docs/conf.py

project = "example"
extensions = ["myst_parser"]
source_suffix = [".rst", ".md"]

And, at docs/index.md, we will create a minimal front page for our documentation.

# Example documentation

Hello world!

You should now have something like this.

example/
├── docs/
│   ├── conf.py
│   ├── index.md
(...)

To build HTML from this source, install sphinx and the MyST Markdown parser

pip install sphinx myst-parser

and then run sphinx-build, pointing it to your directory of source files and a target directory for writing rendered (HTML) output files.

sphinx-build docs/ docs/build/

You should see some log message ending in build succeeded. This created the directory docs/build. Open docs/build/index.html in your web browser to view the documentation.

Essential Features of MyST Markdown

We refer you to the MyST documentation for topics including:

Typography
Tables
Images and figures
Cross-references
Math and equations
Including content from other files

Structure

We began with this structure, having a single documentation page.

example/
├── docs/
│   ├── conf.py
│   ├── index.md
(...)

Suppose we add some tutorials pages in a subdirectory.

example/
├── docs/
│   ├── conf.py
│   ├── index.md
│   └── tutorials/
│       ├── installation.md
│       ├── first-steps.md
│       └── real-application.md
(...)

We can link them from the front page by using the MyST Markdown {toctree} directive.

```{toctree}
tutorials/installation.md
tutorials/first-steps.md
tutorials/real-application.md
```

For more details see the MyST documentation page on organizing content.

Automatically generate reference documentation

Reference documentation provides comprehensive documentation of the API: all the inputs and outputs of every public object in the codebase. This should not be written by hand; that would be tedious and have a high probably of human error or drifting out of sync over time.

MyST recommends using sphinx-autodoc2. However, we currently recommend using the built-in sphinx autodoc and autosummary extensions because they interoperates well with docstrings written to the numpydoc standard. To invoke them, we need to employ yet another syntax (reST). Fortunately, you can simply copy/paste these examples.

In docs/conf.py, add to the list of extensions.

extensions = [
    # whatever you already have in here...
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon",
]

(Note that these extensions come with sphinx, so there is nothing more to install.)

You can document a single object (e.g. function), shown inline on the page

```{eval-rst}
.. autofunction:: example.refraction.snell
    :noindex:
    :toctree: generated
```

Or you can generate a table that links out to documentation for each object.

```{eval-rst}
.. autosummary::
    :nosignatures:
    :toctree: generated

    example.refraction.snell
```

See the guide for more information on how to integrate this into a package, and setup for nox.