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
requirements.txtto 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:
- Create a docs folder inside your repository and populate it, for example with these example files.
conf.pyto add to the python path the folder containing the python package to be documented (sphinx needs to import the package to access the docstrings).:Many other customizations are possible using
import sys sys.path.insert(0, os.path.abspath('../')) # path relative to conf.py
- Compile your project locally by typing:
This generates a simple preview of your documentation (less advanced than rtd) in the folder
$ make html
_build. You can open
_build/index.htmlin your browser to navigate the preview.
- 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.txtunder 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: