Skip to content

Read the Docs Setup

Pablo Prietz edited this page Mar 3, 2022 · 1 revision

The Python Module Skeleton is set up to use the following three technologies for its documentation:

  1. reStructuredText (short rst) - plaintext markup language; files can be found in the docs/ folder
  2. Sphinx - generates HTML from rst; configuration file is located at docs/conf.py
  3. Read the Docs (short RTD) - automating building, versioning, and hosting of the documentation; configuration file is located at .readthedocs.yml

Read the Docs can be configured to automatically

  1. Pull changes from Github
  2. Install this Python module
  3. Build the documentation using Sphinx
  4. Publish the HTML files at your-project-url.readthedocs.io

Setting up a New RTD Project

  1. Go to https://readthedocs.org/dashboard/import/
  2. Select the repository and follow the setup instructions

Versions

RTD provides the possibility to host different versions (equivalent to commits) of your documentation. By default, there are two versions:

  • latest - latest commit on the main branch
  • stable - latest tag corresponding to a final release

Additional Versions

To set up new versions, e.g. for a staging branch, go to https://readthedocs.org/projects/<project>/versions/ and select the tag or branch listed under Activate a version. In the next step, tick the corresponding check boxes:

  • Active - Causes this tag/branch to be built as a new version
  • Hidden - If not selected the version won't be listed in the version selector, accessible at the bottom of every RTD website

The version is accessible via https://<project-name>.readthedocs.io/en/<version>/

Clone this wiki locally