From aed62ab6f8223e7adb662ff2d328654cf754ed98 Mon Sep 17 00:00:00 2001 From: Guangyang Li Date: Wed, 16 Sep 2026 23:04:15 -0400 Subject: [PATCH] **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: ``` 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. --- .readthedocs.yaml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 8303409..9db55a8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -5,14 +5,13 @@ version: 2 # Set the version of Python and other tools you might need +# ubuntu-20.04 was removed as a build image, which fails the build outright rather than +# falling back. Read the Docs supports ubuntu-22.04, ubuntu-24.04, ubuntu-26.04 and +# ubuntu-lts-latest; pin a real version so an image being retired is a deliberate bump. build: - os: ubuntu-20.04 + os: ubuntu-24.04 tools: - python: "3.10" - # You can also specify other tool versions: - # nodejs: "16" - # rust: "1.55" - # golang: "1.17" + python: "3.12" # Build documentation in the docs/ directory with Sphinx sphinx: