Documentation tutorial

Dev meeting, July 2025.

Introduction

The goal of this tutorial is to learn how to publish a documentation for your Python projects. And we will prove you it’s not a big deal! Have a quick look at what you will have built in an hour.

Needless to say that if you are developing a software, a public documentation is mandatory. And if you are a PhD, it is also an interesting knowledge to have. It will give credit to your projects, and greatly facilitate collaboration and handover to new PhDs.

Let’s get started!

Overview of a documentation

Let’s define the scope of this tutorial: we have a Python API that we want to document.

To begin, let’s take inspiration from the community. Among other well known Python libraries, you are probably already familiar with scikit-learn documentation, or numpy’s. Another that often inspires me in niilearn’s.

Even if these documentations differ on some points, we can see common patterns. More precisely, there are some sections that you will often find in an API documentation:

  • An Installation section: the first and most fundamental section with instructions to install the package properly.

  • A Getting Started section: a quick overview of the main features of your package. It is where your “sell” your project!

  • Examples: concrete examples that the user should be able to run on his own.

  • A User Guide: a section where you present in details all the features of the package. All the well know Python projects have an exhaustive user guide, but this section is really time-consuming to work, so I think it shouldn’t be your priority.

  • An API Reference: a section where you document the public Python objects of your API (e.g. your functions and the parameters that they take). We will see that this section is really easy to build from your docstrings.

  • A Contribution Guide: if you want to encourage people to contribute to your project.

Note

If you ask me what is the priority, I would say that an Installation section, a Getting Started section, and an API Reference are a good start. Secondly, I would feed the Examples. The Contribution Guide and particularly the User Guide are a bit more time-consuming to write, and are only expected for more advanced project.

Technical baggage to publish a documentation

To publish a documentation, there are three steps:

  1. write the documentation;

  2. build it: convert your documentation to a publishable website (i.e. a set of html, css, js, etc. files);

  3. deploy it: publish the website on the internet.

Now that I’ve mentioned html, css, and js, I can see that you are afraid. Fortunately, modern tools take care of the nasty things and build automatically your website from the documentation that you have written in a user-friendly format like Markdown.

Two popular tools are Sphinx and MkDocs. MkDocs is more than enough to build a documentation only from markdown files, but in the case of an API, we will prefer Sphinx, that offers really convenient functionalities, such as building automatically the API Reference from docstrings.

Note

If your software is not an API, e.g. a command-line interface, MkDocs may be the right choice. Have a look at Clinica documentation to have an example of what you can do with MkDocs.

To deploy our website, we will try two options: GitHub Pages and Read the Docs.

Today’s tutorial

Now that you have all the required knowledge to start the tutorial, let’s introduce our use case.

We will work on a toy Python library, called neuroplot, focused on neuroimaging data visualization. This library is functional, and you can see some usage examples in the example section, but we will start from a checkpoint when there was no documentation at all (not even docstrings!). Our goal is thus to publish a documentation from scratch!

Clone the repo

The repository of neuroplot is available here.

The first step of the tutorial is to fork the repository (make sure you fork all the branches by unchecking the box “Copy the main branch only”), and then to clone it. Then checkout to the code branch, and create a new branch from the latter:

git checkout code
git checkout -b tutorial

This is the starting point of the tutorial. All the files that you will find are related to Python, and there is nothing related to documentation.

The Python architecture of the project is very simple and looks like this:

src/neuroplot
├── __init__.py
├── plot
│   ├── __init__.py
│   ├── multiple
│   │   ├── __init__.py
│   │   └── multiple_plot.py
│   └── single
│       ├── __init__.py
│       ├── gif.py
│       └── single_plot.py
└── transforms
    ├── __init__.py
    ├── noise.py
    └── rescale_intensity.py

Create your environment

You know the recipe: when you start working with a new project, it is highly encouraged to create a new Python environment. To do that, run:

conda env create -f environment.yml -k
conda activate tuto-doc

Then, install the required dependencies with poetry:

poetry install
Install poetry on macOS
brew install pipx
pipx ensurepath
pipx install poetry

Check that everything is working by running:

poetry run pytest tests/unittests

So far, so good? Great! Let’s get into the nitty-gritty, starting with installing Sphinx.

Important

At the end of each step of the tutorial, we will give you the hash of a git commit that will lead you to the point you should have reached at the end of this step.

For example, if you don’t manage to finish step 1, this will lead you to the expected result:

git checkout --hard cdabe7a2d08df95d844c5f22dd00aa52afbf8ec6