Skip to content

Building and publishing documentation

How to preview docs on your machine and publish them to ReadTheDocs.

Preview locally

From the repository root:

python3 -m venv .venv-docs
.venv-docs/bin/pip install -r docs/requirements.txt
.venv-docs/bin/mkdocs serve

Open http://127.0.0.1:8000 in your browser. MkDocs reloads when you edit files under docs/.

One-shot production build (output in site/):

.venv-docs/bin/mkdocs build

Already have the venv?

If .venv-docs/ exists from a previous session, skip the venv and pip install lines and run .venv-docs/bin/mkdocs serve directly.

What runs during a build

File Role
mkdocs.yml Site config, theme, navigation
docs/requirements.txt Python packages for MkDocs and plugins
.readthedocs.yaml ReadTheDocs build settings (same deps)
tools/gen_ref_pages.py Auto-generates API reference stubs from src/lib/ and src/add_ons/

Hand-authored pages live under docs/ and follow a Try → Quick start → Install → Learn → Reference structure (see mkdocs.yml nav).

API reference pages under reference/ and reference/add_ons/ are generated at build time — do not hand-edit them.

Shared copy-paste blocks: docs/_snippets/ (included via pymdownx Snippets).

Troubleshooting

ModuleNotFoundError during build — use a venv as shown above; do not pip install into the system Python on Debian/Ubuntu (externally-managed-environment error).

Griffe warnings — docstring parameter mismatches in source; warnings only, build still succeeds.

MkDocs 2.0 warning banner — harmless; set DISABLE_MKDOCS_2_WARNING=true to hide it.

ReadTheDocs: "Builds disabled due to consecutive failures"

This project was registered on ReadTheDocs before the docs revamp. RTD kept building main, which had broken MkDocs config (missing nav pages, no docs/requirements.txt, wrong mkdocstrings paths). After 25 failures, RTD auto-disabled builds.

Fix:

  1. Admin → Settings → Advanced → uncheck Disable builds for this project → Save.
  2. Push fixes to main — RTD builds from the default branch; it cannot build changes that exist only locally.
  3. Admin → Versions → ensure latest is active → click Build version.
  4. Confirm the build log shows MkDocs Material and docs/requirements.txt installing — not the old readthedocs theme with missing test2.md.

ReadTheDocs: "Search indexing has been disabled"

Harmless for now — RTD pauses search indexing on inactive projects. After docs are live and receiving traffic:

Admin → Settings → Enable search indexing → Save.

Publish to ReadTheDocs

The public docs URL is https://pydisplay.readthedocs.io. ReadTheDocs reads .readthedocs.yaml from the repo and runs the same MkDocs build as locally.

First-time setup

  1. Go to readthedocs.org and sign in with GitHub (same account that owns PyDevices/pydisplay).

  2. Open the Read the Docs dashboard and click Add project.

  3. Search for PyDevices/pydisplay and import it.

  4. If the repo does not appear, install the Read the Docs GitHub App on the PyDevices org or your fork, then retry.

  5. On the setup form, confirm:

  6. Documentation type: MkDocs (auto-detected from .readthedocs.yaml)
  7. Configuration file: .readthedocs.yaml

  8. Click Next, then This file exists (the config is already in the repo).

  9. Build latest (tracks main):

  10. Go to Admin → Versions.
  11. Ensure latest is Active and set as the default version.

  12. Click Build on latest (or wait for the webhook after pushing to main).

  13. Check the Builds tab. A successful build ends with Documentation built successfully. The site appears at:

  14. https://pydisplay.readthedocs.io/en/latest/
  15. https://pydisplay.readthedocs.io/ when latest is the default

Ongoing

  1. RTD rebuilds automatically when you push to main.
  2. Optionally disable obsolete version slugs under Admin → Versions if any remain from earlier experiments.
  3. Enable search indexing under Settings once the site is live.

Optional: pull request previews

In RTD project Admin → Preview documentation from pull requests, enable PR builds so each PR gets a preview URL before merge.

Rollout checklist (completed)

Step Action Status
Push to main Merge docs revamp and git push origin main Done
RTD build Re-enable builds; Build on latest in Admin → Versions Done
Verify live URLs See table below Done
URL Content
pydisplay.readthedocs.io Full MkDocs site (Material theme)
PyDevices.github.io/pydisplay/ Landing page with links to docs and demo
PyDevices.github.io/pydisplay/demo/ PyScript calculator / REPL / test pages

Pushes to main trigger an automatic RTD rebuild and the deploy-demo workflow for GitHub Pages.

Check GitHub Actions from the CLI

Authenticate once (stores credentials for future sessions):

gh auth login

Then from the repo root:

gh run list --limit 5              # recent workflow runs
gh run watch                       # follow the latest run

Useful after pushing doc or demo changes to confirm the Pages deploy succeeded.

Maintainer reference

More on regenerating packages and micropython-lib publishing: tools/README.md.