Python - Package Documentation

Add docs

Install sphinx and the markdown parser

pip install sphinx myst-parser 

Make a docs directory and run the quick-start

mkdir docs
cd docs

Add markdown and autodoc extensions to

extensions = ['myst_parser',

Make docs files and edit index.rst

  • Edit index.rst to include the information you
  • Add markdown files for each separate page of docs
  • In index.rst add the names of the markdown files (without extensions) to the toctree block. E.g., if we want to include an the docs in and
.. toctree::
   :maxdepth: 2
   :caption: Contents:


Setup automatic function documentation

sphinx-apidoc -f  -o source ../<package-name>

Change the theme

  • Pick a theme (we currently use either spinx-rtd-theme or furo)
  • Install it
pip install sphinx_rtd_theme
  • Change the theme value in in
html_theme = "sphinx_rtd_theme"
  • If using the sphinx_rtd_theme also add it to extensions
extensions = ['myst_parser',

Build the docs

make html

Build docs automatically on readthedocs

Your project should be in an online repository

Add a docs requirements.txt file

In the docs directory add a requirement.txt file that includes the extra packages required for building the docs.


Add .readthedocs.yaml

version: "2"

  os: "ubuntu-22.04"
    python: "3.10"

    - method: pip
      path: .
    - requirements: docs/requirements.txt

  configuration: docs/

Connect your GitHub/GitLab account to readthedocs

  • Go to
  • Click ‘Sign up’
  • Choose ‘Read the Docs Community’
  • Click ‘Sign up with GitHub’ (or GitLab)
  • Follow the instructions

Connect your project

  • Go to
  • Click ‘Import a Project’
  • If the project is listed select it
  • If it is not listed click on ‘Import Manually’ and provide the requested information

Enable builds for PRs

If you want to check the doc builds from your PRs enable this by:

  1. Go to the project dashboard on readthedocs
  2. Select ‘Admin’
  3. Select ‘Advanced Settings’
  4. Click ‘Build pull requests for this project’