govuk-data-science-workshop: 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 src/__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 src module:
.. currentmodule:: src
Then, elsewhere in the body, call the autosummary directive to generate the
docstrings as ReST stub files.
.. autosummary::
:toctree: api/
hello
world
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 src/__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 src module:
```{eval-rst}
.. currentmodule:: src
```
Then, elsewhere in the body, call the autosummary directive to generate the
docstrings as ReST stub files.
```{eval-rst}
.. autosummary::
:toctree: api/
hello
world
```
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:
```