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
sphinx-quickstart

Add markdown and autodoc extensions to `conf.py`

extensions = ['myst_parser',
              'sphinx.ext.autodoc']

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 installation.md and getting-started.md:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   installation
   getting-started

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 conf.py

html_theme = "sphinx_rtd_theme"

If using the sphinx_rtd_theme also add it to extensions

extensions = ['myst_parser',
              'sphinx.ext.autodoc',
              'sphinx_rtd_theme']

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.

myst_parser
sphinx_rtd_theme

Add .readthedocs.yaml

version: "2"

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

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

sphinx:
  configuration: docs/conf.py

Connect your GitHub/GitLab account to readthedocs

Go to https://readthedocs.com/
Click ‘Sign up’
Choose ‘Read the Docs Community’
Click ‘Sign up with GitHub’ (or GitLab)
Follow the instructions

Connect your project

Go to https://readthedocs.org/dashboard/
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:

Go to the project dashboard on readthedocs
Select ‘Admin’
Select ‘Advanced Settings’
Click ‘Build pull requests for this project’