Fix the failing Read the Docs build - #72
Merged
Merged
Conversation
…ree Read the Docs builds all failed, including the two triggered around the 1.2.0 release: ``` build 34603310 finished success=False 2026-09-17T01:49:55Z build 34603240 finished success=False 2026-09-17T01:41:35Z build 34603232 cancelled success=False 2026-09-17T01:40:59Z ``` `.readthedocs.yaml` pinned `build.os: ubuntu-20.04`. That image has been removed: Read the Docs now supports `ubuntu-22.04`, `ubuntu-24.04`, `ubuntu-26.04` and `ubuntu-lts-latest`. An unsupported `build.os` fails the build rather than falling back to something newer. This matters more than it looks. The ReadTheDocs badge and the documentation link in the README, in `README_pypi.rst`, and on the PyPI project page all point at a site that is not rebuilding, so the docs a new user lands on are stale relative to the release that just shipped. ## Change `ubuntu-20.04` to `ubuntu-24.04`, and the Python tool from `3.10` to `3.12` to match CI. Dropped the commented-out `nodejs`/`rust`/`golang` lines that came from the template and were never used. Pinned to a real version rather than `ubuntu-lts-latest`, so the next image retirement is a deliberate bump instead of a silent environment change under the docs. ## Verified Simulated the Read the Docs environment: a clean venv with **only** `requirements_doc.txt` installed, then `sphinx -b html docs`. - Builds successfully. - `autodoc` resolves, confirmed by checking the rendered API Reference actually contains `waffle_chart` and `block_edge_color`. This works without installing the package because `docs/conf.py` puts the repository root on `sys.path`. - Warning count unchanged at six, all pre-existing. Those are cosmetic and cleared separately in a follow-up PR, so this one stays a two-line fix that can be merged immediately. I could not read the build log itself; the Read the Docs API does not expose it without authentication. The removed build image is the only configuration value that is no longer valid, so it is the likely cause, but **worth confirming the next build goes green after merge**. BODY gh pr create --base master --head fix/readthedocs-build --title 'Fix the failing Read the Docs build' --body-file /tmp/pr72.md 2>&1 | tail -1 Fix the failing Read the Docs build The last three Read the Docs builds all failed, including the two around the 1.2.0 release. .readthedocs.yaml pinned build.os: ubuntu-20.04, and that image has been removed. Read the Docs now supports ubuntu-22.04, ubuntu-24.04, ubuntu-26.04 and ubuntu-lts-latest; an unsupported value fails the build rather than falling back. The docs link in the README, in README_pypi.rst and on the PyPI project page all point at that site, so it is stale relative to the release that just shipped. Move to ubuntu-24.04, and the Python tool from 3.10 to 3.12 to match CI. Pin a real version rather than ubuntu-lts-latest so the next retirement is a deliberate bump. Verified by building the docs in a clean venv with only requirements_doc.txt installed, and by checking the rendered API Reference really contains the autodoc output.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The documentation site is currently failing to build. The last three Read the Docs builds all failed, including the two triggered around the 1.2.0 release:
Cause, confirmed by the build log
.readthedocs.yamlpinnedbuild.os: ubuntu-20.04, and that image has been removed. The build fails at config validation, before it ever reaches Sphinx, which is why nothing in the docs themselves needs changing.This matters more than it looks. The ReadTheDocs badge and the documentation link in the README, in
README_pypi.rst, and on the PyPI project page all point at a site that is not rebuilding, so the docs a new user lands on are stale relative to the release that just shipped.Change
ubuntu-20.04toubuntu-24.04, and the Python tool from3.10to3.12to match CI. Dropped the commented-outnodejs/rust/golanglines that came from the template and were never used.Pinned to a real version rather than
ubuntu-lts-latest, so the next image retirement is a deliberate bump instead of a silent environment change under the docs.Verified
Simulated the Read the Docs environment: a clean venv with only
requirements_doc.txtinstalled, thensphinx -b html docs.autodocresolves, confirmed by checking the rendered API Reference actually containswaffle_chartandblock_edge_color. This works without installing the package becausedocs/conf.pyputs the repository root onsys.path.