Documentation

Overview

This page provides information that should be useful to work on the documentation of the project.

It is recommended to start with a very simple version of the documentation (a hello world like page). Follow the whole workflow until the website for the documentation is online, and then keep iterating over this, to add new pages, better styles, new features...

The documentation is usually placed in the directory doc/ in the top level of the project.

There are many open source projects using the same format as we propose here, as it's quite standard. Feel free to go to their repositories on GitHub, see how they implemented things, and copy them if they are useful. That's part of the beauty of open source software.

restructuredText

In Python, it's common to use restructuredText (rst) for documentation. A markdown language that looks like this:

Title
=====

A paragraph of the documentation. This can contain for example **bold** text,
and other formats. Links to pages like `GitHub <https://github.com>`_ are formatted
this way. Code (monospace text) can be created with backticks, like in `print('Hello world')`.

- A list
- Can be implemented with the minus sign
- And they must have a blank line before

Sphinx

While the documentation is some times read directly from the restructuredText files, most users would like to read them in a website (and find them using a search engine). Most Python projects use Sphinx to generate the html documentation from the rst files. It can also generate the documentation in pdf, or in formats for e-books, but html is usually enough.

The Sphinx documentation has a Getting Started page, that should be helpful to set up a new project.

Read the docs

By using Sphinx, it's possible to generate a web site with our project documentation in our local laptop. But ideally, we would like to generate it from the GitHub repository, and publish it in an online server, so the documentation of our project can be accessed by anyone online. Read the docs is a platform that was created to make this simple. Information on how to set up an account and generate the documentation for our project can be found in their website.

You may know the creator of Read the docs (and Python Software Foundation director) Eric Holscher, as he participated in one of our sprints.

Documentation sections

After you managed to have a simple version of the documentation online, you can add more pages to it. The usual pages projects have are:

• Installation (instructions for the users to know how to install your software)
• Getting started / Tutorial (guided steps to have an idea on what is the project about and how to use it)
• User guide (pages with specific topics/features, theory that complements the project...)
• API reference (documentation of every object implemented, such as classes, functions...)

API reference

Sphinx can generate automatically the API reference from the docstrings in the code. A docstring is documentation written inside the source code in this way:

def add(num1, num2):
    """
    Return the sum of two numbers.

    Parameters
    ----------
    num1 : int
        First number to sum.
    num2 : int
        Second number to sum.

    Returns
    -------
    int
        The sum of the two numbers.
    """
    return num1 + num2

Sphinx has a extension system, and one of the available extensions is named autodoc. This can be used to automatically generate the documentation, by using Sphinx directives like .. automodule::.

Note that the previous docstring is formatted in a style named numpydoc. A Sphinx numpydoc extensions also needs to be installed to understand that format.