writing_sphinx_documentation.md

Writing Sphinx documentation

This project is set up to produce documentation using Sphinx; this page should give you a quick overview on how to write documentation for it. If you'd like to know how to write good documentation take a look at Write the Docs guide on writing documentation. For Agile projects, consider documenting late as well.

Why should I bother? And why Sphinx?

Keeping as much of the documentation in a centralised location is a good thing. It means contributors, users, and anyone else can quickly find as much information as they need to understand and/or run what you've done.

Sphinx is a Python-based package to compile documentation into different formats, including HTML. This means you can write your documentation and, with a single terminal command, build it into a searchable website.

It's widely used, such as for the documentation of the pandas, and PyTorch Python packages as well as many others. It is highly customisable with different extensions, and themes. Included with this project is:

• support for both reStructuredText (ReST), and ReST-enabled Markdown;
• automatic building of documentation from Python docstrings; and
• support for ReStructuredText, NumPy, or Google docstring formats.

Creating a searchable website

To create a website with your documentation, run the following command in your terminal at the top-level of this project:

make docs

This should create an HTML version of your documentation accessible from docs/_build/index.html.

Writing in reStructuredText

Sphinx provides good documentation on writing in ReST — we would highly recommend reading that for guidance. We will cover automatically creating docstrings in the next subsection.

Automatically creating docstring documentation (ReST)

Let us say that {{ cookiecutter.repo_name }}/__init__.py has functions called hello and world imported into it, and both have docstrings. To automatically generate docstring documentation, create a ReST file, and add the following line to reference the {{ cookiecutter.repo_name }} module:

.. currentmodule:: {{ cookiecutter.repo_name }}

Then, elsewhere in the body, call the autosummary directive to generate the docstrings as ReST stub files.

This will create something similar to the pandas API reference.

Writing in ReST-enabled Markdown

We use the myst-parser package (MyST) to write Markdown that can also include ReST elements. The package documentation is detailed, so we would recommend reviewing it. We will cover some of the more widely used elements in the following subsections.

Embedding ReST directives

Most ReST directives can be embedded into MyST Markdown.

Automatically creating docstring documentation (MyST Markdown)

Let us say that {{ cookiecutter.repo_name }}/__init__.py has functions called hello and world imported into it, and both have docstrings. To automatically generate docstring documentation, create a Markdown file, and add the following line to reference the {{ cookiecutter.repo_name }} module:

```{eval-rst}
.. currentmodule:: {{ cookiecutter.repo_name }}
```

Then, elsewhere in the body, call the autosummary directive to generate the docstrings as ReST stub files.

Including Markdown files outside the docs folder

MyST lets you include Markdown files outside the docs folder.

If a Markdown file (../example.md) only contains links that do not reference anything else in this project (including images), create a Markdown file within the docs folder with the following lines:

```{include} ../example.md
```

However, if it includes relative links referencing other files in this project (including images), we need to tell MyST what those links actually refer. For example, if the relative link is ../hello/world.md, we need to create a Markdown file within the docs folder with the following lines:

```{include} ../example.md
:relative-docs: ../hello
:relative-images:
```