Read the Docs Implementation from GitHub

This guide documents how to host U-MIMIC documentation on Read the Docs (RTD) with GitHub as the source of truth.

Architecture

  1. Code and docs live in GitHub.

  2. RTD imports the GitHub repository.

  3. Pushes and pull requests trigger RTD builds.

  4. RTD serves versioned docs and PR previews.

Repository files required

The repository now includes:

  • .readthedocs.yaml: RTD build configuration

  • docs/conf.py: Sphinx config

  • docs/index.md: docs landing page

  • this guide (docs/readthedocs-github.md)

1. Import the repository into Read the Docs

  1. Sign in to RTD with your GitHub account.

  2. Click Import a Project.

  3. Select the U-MIMIC GitHub repository.

  4. Confirm the default branch (usually main).

RTD will detect .readthedocs.yaml at repository root and use it for builds.

2. Connect GitHub webhooks

After importing:

  1. Open RTD project Admin -> Integrations.

  2. Ensure GitHub integration webhook is active.

  3. In GitHub, check Settings -> Webhooks for an RTD webhook entry.

This ensures docs rebuild on push and pull request events.

3. Build configuration details

RTD uses .readthedocs.yaml:

  • Python: 3.11

  • OS image: Ubuntu 24.04

  • Builder: Sphinx with config at docs/conf.py

  • Install command: pip install .[docs]

.[docs] comes from pyproject.toml and currently installs:

  • sphinx

  • myst-parser

4. Local validation before pushing

Run docs build locally before opening a PR:

python -m pip install -e ".[docs]"
sphinx-build -b html docs docs/_build/html

If build succeeds, open docs/_build/html/index.html to preview.

5. Configure versions and preview behavior in RTD

In RTD project settings:

  1. Versions: enable at least latest and stable.

  2. Automation Rules: enable pull request builds.

  3. Optionally hide inactive branches to reduce noise.

Recommended policy:

  • stable: latest tagged release branch/tag

  • latest: default branch (main)

  • PR builds: enabled for contributor review

6. Add docs status to GitHub (optional)

You can add the RTD badge to README.md and enable required checks in branch protection:

  • RTD build status

  • repo test workflow(s)

This prevents merges that break documentation.

7. Troubleshooting

Build fails with missing dependencies

Cause: docs dependency not included in pyproject.toml extras.
Fix: add package to [project.optional-dependencies].docs and retry build.

RTD does not rebuild on push

Cause: webhook missing or disabled.
Fix: re-sync integration from RTD Admin -> Integrations.

Docs page renders empty navigation

Cause: missing toctree entries in docs/index.md.
Fix: include each documentation page in the toctree.

Operational checklist

Before each release:

  1. Build docs locally with Sphinx.

  2. Push docs changes to GitHub.

  3. Confirm RTD build is green for latest.

  4. Create release tag.

  5. Confirm stable version is updated in RTD.

Acknowledgements

Parts of this documentation were created with assistance from ChatGPT Codex and Claude Code.