Create a documentation

This document describes the steps to create and publish a project documentation to Read the Docs.

Workflow

Docs are being autogenerated and published at readthedocs.io (RtD) after changes to the upstream repository. The repository itself contains some build configuration and, of course, the contents of the documention. Autogeneration requires the repository to be connected with RtD.

Markup

The documentation is using the reStructuredText markup.

Installation

Note

There is no installation required at all to create docs on RtD. However, to be able to develop and preview the documentation, it makes sense to build them locally.

Python

The documentation is built using Sphinx, which requires python3 and the python package manager pip to be installed on the local machine.

$ python3 --version
Python 3.8.6
$ pip --version
pip 21.0.1 from ../lib/python3.8/site-packages/pip (python 3.8)

Shpinx

Installing and setting up Sphinx is described in detail here: Getting started

The projects needs to have a root docs folder where all contents and configuration live.

cd project_root
mkdir docs
cd docs
spinx-quickstart

Note

When running the sphinx-quickstart command and asked:

  • leave release empty

  • separate build and source folder

Markdown support

To be able to import the project’s README.md into the docs, install and configure also the m2r2 tool.

RtD Theme

Docs can be themed, the Read the Docs theme needs to be installed and configured as well.

Requirements file

You should add all installed pip requirements to a docs/requirements.txt file in order to have RtD use the right versions. Example:

sphinx==3.2.1
sphinx_rtd_theme==0.5.1
m2r2==0.2.7

Creating the docs

cd docs
make html
firefox build/html/index.html

Create a docs/.gitignore file to exclude the local documentation build:

build

Adding docs to RtD

  • Create an account on RtD and log in

  • Grant RtD access to your team’s Github, Bitbucket or Gitlab account

  • Click Import a project and follow the instructions

  • Disable PDF and EPub build at projects advanced settings to avoid unnecessary docs generations.

Import Guide

VSCode extensions

The reStructuredText extension is recommended to write and preview the documentation using VSCode.