Sphinx

Sphinx is a great tool for documenting Python code. It uses autodocs to generate API like documentation for you but also allows you to structure the pages and sections of documentation. This allows the user to add further details and logic to the documentation.

For a full tutorial and documentation on how to use Sphinx: https://www.sphinx-doc.org/en/master/tutorial/index.html

Here we present a quick run through of how to set up and use some of the key functions of Sphinx.

Set up

Sphinx is quick and easy to get started it can be installed through pip:

pip install sphinx

Then it can be set up with the built into a docs directory with the quickstart function:

sphinx-quickstart docs

This will set up a folder structure for the source and build files:

docs

├── build

├── make.bat

├── Makefile

└── source

├── conf.py

├── index.rst

├── _static

└── _templates

From here we can edit the index.rst file to add content and create new .rst file in the source directory to generate new pages/sections of documentation.

Autodocs

Assuming your code is documented in a regular style (see Python docstrings) then Sphinx can be used to generate API style documentation. To do this we can either generate an API for all of the code or create these docs in specific places in our documentation.

First we must add 'sphinx.ext.autodoc' to the extensions in the conf.py file. Then we can add references to the docstrings in the reStructured text. This can be for a function, class, module or exceptions.

.. autofunction:: example.myfunction

.. automodule:: example

:members:

.. autoclass:: example.MyClass

:members:

To make referencing these this easy we actually need to add the path to Sphinx so it can find things in our package by adding the following to the top of the conf.py file:

sys.path.insert(0, os.path.abspath('.'))

sys.path.insert(0, '/home/username/PycharmProjects/Example/')

To tidy things up we add some titles:

###########

Example Docs

###########

Functions

========

.. autofunction:: example.myfunction

Module

======

.. automodule:: example

:members:

Class

=====

.. autoclass:: example.MyClass

:members:

This produces beautiful documentation of the sort you can see here: https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html

Adding

We can add titles and organisation to the code and we can go further. We can include anything we can write in reStructured Text. This means that we can include graphs, code snippets, equations, lists and tables. We can even directly import latex or use latex inside our reStructuredText. So we can write up the algorithm for our research code for a paper and use it in our documentation too. Graphs, charts and tables from papers also provide great examples of what your code does in the documentation. Information and guides on these features can be found in Sphinx's documentation: https://www.sphinx-doc.org/en/master/usage/quickstart.html

There are however a few recommended additional pages to add, beyond the code description itself:

Set up: How do I install and use the code? What dependencies do I need to install?
Replication: It can be good to include for specific papers instructions of how to replicate results.
Homepage: Sphinx documentation automatically starts with the index.rst make sure to populate this with a summary description of what the package is and what it is for and any other information you want as an introduction to your package.

Building

Once we have written the documentation we need to make it available to users. Sphinx offers several options for output including html and latex. This means from one set of work we can develop both a website and a manual.

To do this we simply run either:

make html

make latex

These will build the correct files in corresponding directories in the build directory.

Publishing

If you have chosen to use GitHub for your Version Control you can publish the html documentation produced by Sphinx using GitHub Pages. To do this you need to add only two files to your docs folder and then turn on the pages option in your repository settings.

First you need to add a .nojekyll file. It doesn't have any content but will tell GitHub Pages that you are not using a jekyll site. The second is a index.html file. This is required to redirect GitHub Pages from the docs directory to the index.html file in the build/html directory.

So now we push the docs including the built html and new files to GitHub on the main branch. The site should be published already but feel free to check the branch and source directory settings by going to the repository on GitHub and selecting: Settings -> Pages. Here there should be a link to the site itself and the branch and source settings. If you want to take more care in updating your documentation you can always put it on its own branch that way it will only update when you push to that branch.

That's all you need to get your documentation website started though. If you want to change the look of the site consider using one of the built in themes or take a look at other available themes here: https://sphinx-themes.org/

Personally I'm a fan of the Read the Docs theme which can be installed via pip with:

pip install sphinx-rtd-theme

Page updated

Report abuse