Skip to content

Sphinx - Read the Docs documentation

G. Iadarola and R. De Maria

For python packages, we found particularly convenient to use sphinx to document the code and to host the documentation on Read the Docs. The API documentation can be generated by sphinx from the docstrings in the code.

The main steps to create a sphinx-rtd documentation are the following:

Install sphinx and rtd-theme

  • Install sphinx and the rdt-theme:
    $ pip install sphinx
    $ pip install sphinx-rtd-theme
    

Start documentation pages

  • The code to be documented needs to be hosted in a GitHub or GitLab account
  • Add requirements.txt to your repository. In order to get documentation from the docstrings, Read the Docs will need to import your python package in a python virtual environment. It will install the dependencies based on the requirements file, which simply consists in the list of packages that need to be installed. For example:
    numpy
    scipy
    
  • Create a docs folder inside your repository and populate it, for example with these example files.
  • Edit conf.py to add to the python path the folder containing the python package to be documented (sphinx needs to import the package to access the docstrings).:
    import sys
    sys.path.insert(0, os.path.abspath('../')) # path relative to conf.py
    
    Many other customizations are possible using conf.py.
  • Compile your project locally by typing:
    $ make html
    
    This generates a simple preview of your documentation (less advanced than rtd) in the folder _build. You can open _build/index.html in your browser to navigate the preview.

On readthedocs.org

  • Create an account on https://readthedocs.org (the easiest is to link it to your github account), it you don't already have one.
  • Add a project linked to your GitHub/GitLab repository.
  • Add requirements file by specifying requirements.txt under Admin > Advanced Settings -> Requirements file.

Edit your documentation

A lot of information about the RST format used in the documentation and about the sphinx doc generation can be found in these tutorials:

An example of documentation from our team can be found at: