Documentation in Read the Docs

Read the Docs hosts documentations. It can be used to automatically generate and store the project documentation.

You can find information of how to use it in the Read the Docs documentation.

Setting up Read the Docs

1. Log into the Read the Docs page and import your project.

2. After the initial configuration is done, got to Advanced Settings to:

   1. Check the install project option if you want to document your code.

   2. Add a requirements file.

   3. check the use system packages to make the build proccess faster.

   4. Choose the right Python Interpreter for your project.

3. Under the versions page, select the different versions you want to build the documentation for.

   Note

   Versions are taken from the branches and from the tags.

4. Add a webhook to automate the build process when a commit is made.

The requirements file

The requirement file contains some requirements that are for the Read the Docs build process and not for others. This is a simple .txt file with a list of python packages. The suggestion is to have a file docs/requirements.txt.

Example:

sphinxcontrib-napoleon

At the moment of writing some issues with the build process of Read the Docs force us to have the rest of libraries needed for the project specified in requirements.txt.

Using conda

At the time of writing, Python 3.5 was not supported directly by Read the Docs, so conda was used as a workaround.

A conda environment can be created to install the packages. To do so:

1. Create a conda YAML file with the packages your need.

   You can create a local environement and export

   it to a file.

2. Create a readthedocs.yml file:

   requirements_file: docs/source/requirements.txt
   conda:
     file: docs/source/environment.yml
   python:
     setup_py_install: true
   

Warning

At the time of writing, I have not been able to make the requirements.txt file work with conda. If you have some special libraries there that are not in the environment (e.g. sphinxcontrib-napoleon) add them to the conda YAML file.

Hint

If you have the project installed in conda environment, remove it from the YAML file, so you ensure that the correct version is being build.

Recently ReadTheDocs have not only added support for pyenv, but also for Docker, so it is more easy to use different Python versions. You need to update your readthedocs.yml file as follow:

build:
    image: latest

python:
    version: 3.6

More information in this post: https://blog.readthedocs.com/python-36-support/

Using ReadTheDocs HTML theme

When building the documentation using ReadTheDocs, you can choose to use their own HTML theme while when you build in local you can use another theme. To do so, when building in ReadTheDocs, the environment variable READTHEDOCS is set to True, so you can check it. For example, in the conf.py file:

if os.environ.get('READTHEDOCS'):
    html_theme = 'sphinx_rtd_theme'
else:
    html_theme = 'nature'

Note

The ReadTheDocs HTML theme can also be used locally. You can install it through pip or conda. The package is named: sphinx_rtd_theme.