From a1948e3189db303ea782a7db80db56b4169a62b9 Mon Sep 17 00:00:00 2001 From: Vitor Bandeira Date: Sun, 8 Nov 2026 13:44:07 -0300 Subject: [PATCH 1/3] docs: build with Python 3.12 and Sphinx 9.1 Read the Docs now builds on ubuntu-24.04 with Python 3.12. The docs lock is regenerated for Python 3.12: - sphinx 5.3.0 -> 9.1.1, docutils 0.19 -> 0.22.4 - myst-parser 1.0.0 -> 5.1.0 - sphinx-book-theme 1.1.3 -> 1.4.0, pydata-sphinx-theme 0.15.4 -> 0.20.0 - sphinx-external-toc 0.3.1 -> 1.1.0 requirements.in caps sphinx at 9.1 and docutils below 0.23, because newer releases need Python 3.13. The lock also updates anyio, certifi, soupsieve, starlette and urllib3 to releases with no known OSV advisories. Signed-off-by: Vitor Bandeira --- .readthedocs.yaml | 4 +- docs/README.md | 8 +-- docs/requirements.in | 12 ++-- docs/requirements_lock.txt | 112 +++++++++++++++++++------------------ 4 files changed, 71 insertions(+), 65 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9c99c03866..efc352ca79 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,9 +6,9 @@ version: 2 # Set the OS, Python version and other tools you might need build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: - python: "3.10" + python: "3.12" # Build documentation in the "docs/" directory with Sphinx sphinx: diff --git a/docs/README.md b/docs/README.md index 81cddb3edd..d9cfb562db 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,8 +11,8 @@ repository and is published at ### Requires -- Python 3.10 — the version Read the Docs builds with (see `.readthedocs.yaml`). - The pinned Sphinx release does not run on Python 3.13 or newer. +- Python 3.12 or newer — Read the Docs builds with 3.12 (see `.readthedocs.yaml`). + The pinned Sphinx release needs Python 3.12 or newer. - `pip` - `virtualenv` (or the standard-library `venv`) @@ -29,10 +29,10 @@ pip install -r docs/requirements_lock.txt `docs/requirements_lock.txt` is the hash-pinned lock file that Read the Docs installs, so a local build matches the published one. The direct dependencies are listed in `docs/requirements.in`; after editing that file, regenerate the -lock with: +lock with `uv` for Python 3.12: ``` shell -pip-compile --generate-hashes --output-file=docs/requirements_lock.txt docs/requirements.in +uv pip compile --generate-hashes --python-version 3.12 --output-file=docs/requirements_lock.txt docs/requirements.in ``` ### Build diff --git a/docs/requirements.in b/docs/requirements.in index df2e6dac48..15173f1274 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,8 +1,12 @@ -sphinx-external-toc==0.3.1 -sphinx +sphinx-external-toc==1.1.0 +# sphinx 9.2 and docutils 0.23 need Python 3.13; the docs build uses 3.12. +sphinx~=9.1.0 +docutils>=0.22,<0.23 sphinx-autobuild -myst-parser -sphinx-book-theme +myst-parser~=5.1.0 +# sphinx-book-theme 1.4.0 supports pydata-sphinx-theme 0.20.x. +sphinx-book-theme==1.4.0 +pydata-sphinx-theme==0.20.0 sphinx-copybutton sphinxcontrib-mermaid sphinx-llm diff --git a/docs/requirements_lock.txt b/docs/requirements_lock.txt index 4da13611a7..a6a2f89d8d 100644 --- a/docs/requirements_lock.txt +++ b/docs/requirements_lock.txt @@ -1,9 +1,5 @@ -# -# This file is autogenerated by pip-compile with Python 3.10 -# by the following command: -# -# pip-compile --generate-hashes --output-file=docs/requirements_lock.txt docs/requirements.in -# +# This file was autogenerated by uv via the following command: +# uv pip compile --generate-hashes --python-version 3.12 --output-file=docs/requirements_lock.txt docs/requirements.in accessible-pygments==0.0.5 \ --hash=sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872 \ --hash=sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7 @@ -12,9 +8,9 @@ alabaster==0.7.16 \ --hash=sha256:75a8b99c28a5dad50dd7f8ccdd447a121ddb3892da9e53d1ca5cca3106d58d65 \ --hash=sha256:b46733c07dce03ae4e150330b975c75737fa60f0a7c591b6c8bf4928a28e2c92 # via sphinx -anyio==4.13.0 \ - --hash=sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708 \ - --hash=sha256:334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc +anyio==4.14.2 \ + --hash=sha256:9f505dda5ac9f0c8309b5e8bd445a8c2bf7246f3ce950121e45ea15bc41d1494 \ + --hash=sha256:cfa139f3ed1a23ee8f88a145ddb5ac7605b8bbfd8592baacd7ce3d8bb4313c7f # via # starlette # watchfiles @@ -28,9 +24,9 @@ beautifulsoup4==4.14.3 \ --hash=sha256:0918bfe44902e6ad8d57732ba310582e98da931428d231a5ecb9e7c703a735bb \ --hash=sha256:6292b1c5186d356bba669ef9f7f051757099565ad9ada5dd630bd9de5fa7fb86 # via pydata-sphinx-theme -certifi==2026.5.20 \ - --hash=sha256:3c52e209ba0a4ad7aebe60436a4ab349c39e1e602e8c134221e546902ad25897 \ - --hash=sha256:69dea482ab64caa7b9f6aba1c6bf48bb6a5448d1c0f1b17ab42ad8c763a5344d +certifi==2026.10.23 \ + --hash=sha256:a9895e6e2758b371e0545e321a3a8fd1fcfd9829ada8824a936dfb16aaaf36cd \ + --hash=sha256:e9b54de76e530bb6cf0ccd036787103acb58fd42ba930ea8bf948ddbaa2f61d1 # via requests charset-normalizer==3.4.7 \ --hash=sha256:007d05ec7321d12a40227aae9e2bc6dca73f3cb21058999a1df9e193555a9dcc \ @@ -173,18 +169,15 @@ colorama==0.4.6 \ --hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \ --hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6 # via sphinx-autobuild -docutils==0.19 \ - --hash=sha256:33995a6753c30b7f577febfc2c50411fec6aac7f7ffeb7c4cfe5991072dcf9e6 \ - --hash=sha256:5e1de4d849fee02c63b040a4a3fd567f4ab104defd8a5511fbbc24a8a017efbc +docutils==0.22.4 \ + --hash=sha256:4db53b1fde9abecbb74d91230d32ab626d94f6badfc575d6db9194a49df29968 \ + --hash=sha256:d0013f540772d1420576855455d050a2180186c91c15779301ac2ccb3eeb68de # via + # -r docs/requirements.in # myst-parser # pydata-sphinx-theme # sphinx # sphinx-markdown-builder -exceptiongroup==1.3.1 \ - --hash=sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219 \ - --hash=sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598 - # via anyio h11==0.16.0 \ --hash=sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1 \ --hash=sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86 @@ -204,11 +197,12 @@ jinja2==3.1.6 \ --hash=sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67 # via # myst-parser + # pydata-sphinx-theme # sphinx # sphinxcontrib-mermaid -markdown-it-py==2.2.0 \ - --hash=sha256:5a35f8d1870171d9acc47b99612dc146129b631baf04970128b568f190d0cc30 \ - --hash=sha256:7c9a5e412688bc771c67432cbfebcdd686c93ce6484913dccf06cb5a0bea35a1 +markdown-it-py==4.2.0 \ + --hash=sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49 \ + --hash=sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a # via # mdit-py-plugins # myst-parser @@ -303,28 +297,28 @@ markupsafe==3.0.3 \ --hash=sha256:f9e130248f4462aaa8e2552d547f36ddadbeaa573879158d721bbd33dfe4743a \ --hash=sha256:fed51ac40f757d41b7c48425901843666a6677e3e8eb0abcff09e4ba6e664f50 # via jinja2 -mdit-py-plugins==0.3.5 \ - --hash=sha256:ca9a0714ea59a24b2b044a1831f48d817dd0c817e84339f20e7889f392d77c4e \ - --hash=sha256:eee0adc7195e5827e17e02d2a258a2ba159944a0748f59c5099a4a27f78fcf6a +mdit-py-plugins==0.6.1 \ + --hash=sha256:214c82fb2ac524472ab6a5bcab1de80f73b50443e187f401bfd77efbc7c6481d \ + --hash=sha256:a2bca0f039f39dbd35fb74ae1b5f998608c437463371f0ff7f49a19a17a114d0 # via myst-parser mdurl==0.1.2 \ --hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \ --hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba # via markdown-it-py -myst-parser==1.0.0 \ - --hash=sha256:502845659313099542bd38a2ae62f01360e7dd4b1310f025dd014dfc0439cdae \ - --hash=sha256:69fb40a586c6fa68995e6521ac0a525793935db7e724ca9bac1d33be51be9a4c +myst-parser==5.1.0 \ + --hash=sha256:9c91c52b3cdb4d94a6506e4fab4e2f296c7623a0da0dcbe6de1565c3dad67a8a \ + --hash=sha256:ab69322dc6719dcc7f296479dbb70181b66df6ed315064f92dbc85c0e1bf2f02 # via -r docs/requirements.in packaging==26.2 \ --hash=sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e \ --hash=sha256:ff452ff5a3e828ce110190feff1178bb1f2ea2281fa2075aadb987c2fb221661 + # via sphinx +pydata-sphinx-theme==0.20.0 \ + --hash=sha256:0da172d41e19a66de875f4002f7054b385372ec65763852193791e658d50bb4a \ + --hash=sha256:56744483c9d72c783e075de716ab95d486108b69605df7528078090b73f11f69 # via - # pydata-sphinx-theme - # sphinx -pydata-sphinx-theme==0.15.4 \ - --hash=sha256:2136ad0e9500d0949f96167e63f3e298620040aea8f9c74621959eda5d4cf8e6 \ - --hash=sha256:7762ec0ac59df3acecf49fd2f889e1b4565dbce8b88b2e29ee06fdd90645a06d - # via sphinx-book-theme + # -r docs/requirements.in + # sphinx-book-theme pygments==2.20.0 \ --hash=sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f \ --hash=sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176 @@ -413,18 +407,24 @@ pyyaml==6.0.3 \ requests==2.34.2 \ --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0 \ --hash=sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed + # via + # pydata-sphinx-theme + # sphinx +roman-numerals==4.1.0 \ + --hash=sha256:1af8b147eb1405d5839e78aeb93131690495fe9da5c91856cb33ad55a7f1e5b2 \ + --hash=sha256:647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7 # via sphinx snowballstemmer==3.1.0 \ --hash=sha256:17e6d1da216aa07db6dad37139ea70cf13c4b2e9a096f6e64a9648fc657d3154 \ --hash=sha256:fd9e34526b23340cd23ffea6c9f9760974ecc2c2ac9e1d81401443ccdb2a801f # via sphinx -soupsieve==2.8.4 \ - --hash=sha256:e121fd02e975c695e4e9e8774a5ee35d74714b59307868dcc5319ad2d9e3328e \ - --hash=sha256:e7e6b0769c8f51ed59acab6e994b00621096cfb1c640a7509295987388fbaf65 +soupsieve==4.0.1 \ + --hash=sha256:2e68cf7dd5a0f29d81f9d485275ccf294e6475f615e211895d91cb81f8614f04 \ + --hash=sha256:7621e3c5f6b371ed2c5eabaac5de300ac3d66d05e6d7f34783e31b63c4f90c75 # via beautifulsoup4 -sphinx==5.3.0 \ - --hash=sha256:060ca5c9f7ba57a08a1219e547b269fadf125ae25b06b9fa7f66768efb652d6d \ - --hash=sha256:51026de0a9ff9fc13c05d74913ad66047e104f56a129ff73e174eb5c3ee794b5 +sphinx==9.1.1 \ + --hash=sha256:48b627f02908f22c601b3ba9c7b17265b4f315dd05c8bc64cd4da41183f44fbc \ + --hash=sha256:f8b60013ce25017be41a509e5c2d265bc1918410061315c36b809c7f335646c0 # via # -r docs/requirements.in # myst-parser @@ -435,22 +435,23 @@ sphinx==5.3.0 \ # sphinx-external-toc # sphinx-llm # sphinx-markdown-builder + # sphinx-multitoc-numbering # sphinxcontrib-mermaid sphinx-autobuild==2024.10.3 \ --hash=sha256:158e16c36f9d633e613c9aaf81c19b0fc458ca78b112533b20dafcda430d60fa \ --hash=sha256:248150f8f333e825107b6d4b86113ab28fa51750e5f9ae63b59dc339be951fb1 # via -r docs/requirements.in -sphinx-book-theme==1.1.3 \ - --hash=sha256:1f25483b1846cb3d353a6bc61b3b45b031f4acf845665d7da90e01ae0aef5b4d \ - --hash=sha256:a554a9a7ac3881979a87a2b10f633aa2a5706e72218a10f71be38b3c9e831ae9 +sphinx-book-theme==1.4.0 \ + --hash=sha256:10fd57d667ee0b565928c3ce95562e281c5d1b94bd5a2aafc5cd41a5d498dcd0 \ + --hash=sha256:fee3cd70573d9a8cd4ab380a3cb1f11139c24dcaa2cf47d06d7f924f1b44eaff # via -r docs/requirements.in sphinx-copybutton==0.5.2 \ --hash=sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd \ --hash=sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e # via -r docs/requirements.in -sphinx-external-toc==0.3.1 \ - --hash=sha256:9c8ea9980ea0e57bf3ce98f6a400f9b69eb1df808f7dd796c9c8cc1873d8b355 \ - --hash=sha256:cd93c1e7599327b2a728db12d9819068ce719c4b037ffc62e47f20ffb6310fb3 +sphinx-external-toc==1.1.0 \ + --hash=sha256:26c390b8d85aa641366fed2d3674910ec6820f48b91027affef485a2655ad7d0 \ + --hash=sha256:f81833865006f6b4a9b2550a2474a6e3d7e7f2cb23ba23309260577ea65552f6 # via -r docs/requirements.in sphinx-llm==0.4.1 \ --hash=sha256:0789185dcbbecc00b5e25aa3db6342b98dad6a9def96088a9e50fa0203fda090 \ @@ -460,6 +461,10 @@ sphinx-markdown-builder==0.6.10 \ --hash=sha256:16d86738b9ac69fcbc86e373c31c6402c30af1fa8d98d0f62cc5f38bfe5fc26e \ --hash=sha256:cd5acf88d52ea0146a712fd557404f10326dff3428a78ba928e59b1727fd4a86 # via sphinx-llm +sphinx-multitoc-numbering==0.1.3 \ + --hash=sha256:33d2e707a9b2b8ad636b3d4302e658a008025106fe0474046c651144c26d8514 \ + --hash=sha256:c9607671ac511236fa5d61a7491c1031e700e8d498c9d2418e6c61d1251209ae + # via sphinx-external-toc sphinxcontrib-applehelp==2.0.0 \ --hash=sha256:2f29ef331735ce958efa4734873f084941970894c6090408b079c61b2e1c06d1 \ --hash=sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5 @@ -488,9 +493,9 @@ sphinxcontrib-serializinghtml==2.0.0 \ --hash=sha256:6e2cb0eef194e10c27ec0023bfeb25badbbb5868244cf5bc5bdc04e4464bf331 \ --hash=sha256:e9d912827f872c029017a53f0ef2180b327c3f7fd23c87229f7a8e8b70031d4d # via sphinx -starlette==1.2.0 \ - --hash=sha256:36e0c76ac59157e75dc4b3bdeafba97fb04eaf1878045f15dbef666a6f092ed7 \ - --hash=sha256:3c5a6b23fff42492914e93890bb80cbfea72dbf37de268eec06185d62a4ca553 +starlette==1.10.0 \ + --hash=sha256:478c0ab3b4ced6e82719849c118fa406f0278a3499c1a898cd15cd31bdc38ce4 \ + --hash=sha256:b8399098d4c1e3522734f7235dc79b1fc967f96cf139c81e0fa30479e0685f9b # via sphinx-autobuild tabulate==0.10.0 \ --hash=sha256:e2cfde8f79420f6deeffdeda9aaec3b6bc5abce947655d17ac662b126e48a60d \ @@ -502,13 +507,10 @@ typing-extensions==4.15.0 \ # via # anyio # beautifulsoup4 - # exceptiongroup - # pydata-sphinx-theme # starlette - # uvicorn -urllib3==2.7.0 \ - --hash=sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c \ - --hash=sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897 +urllib3==2.8.0 \ + --hash=sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3 \ + --hash=sha256:63bf2ead4c879426ebf22ef2a781eeb4aa3b4ae798a0435506f8687fd5bb9b63 # via requests uvicorn==0.48.0 \ --hash=sha256:48097851328b87ec36117d3d575234519eb58c2b22d79666e9bbc6c49a761dad \ From 7d2f12967faafcdf259b32b336515e6b973b2b58 Mon Sep 17 00:00:00 2001 From: Vitor Bandeira Date: Mon, 9 Nov 2026 10:22:16 -0300 Subject: [PATCH 2/3] docs: lock imagesize 2.0.1 imagesize 2.0.0 declares Requires-Python <3.15, so the lock did not install on Python 3.15 although the README asks for 3.12 or newer. 2.0.1 has no upper bound. Signed-off-by: Vitor Bandeira --- docs/requirements_lock.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/requirements_lock.txt b/docs/requirements_lock.txt index a6a2f89d8d..11774be118 100644 --- a/docs/requirements_lock.txt +++ b/docs/requirements_lock.txt @@ -188,9 +188,9 @@ idna==3.17 \ # via # anyio # requests -imagesize==2.0.0 \ - --hash=sha256:5667c5bbb57ab3f1fa4bc366f4fbc971db3d5ed011fd2715fd8001f782718d96 \ - --hash=sha256:8e8358c4a05c304f1fccf7ff96f036e7243a189e9e42e90851993c558cfe9ee3 +imagesize==2.0.1 \ + --hash=sha256:b2ba6a4dea487a7ebcd53248d3476aca449d30db12a2dde5e0c5ca9624fd77e5 \ + --hash=sha256:ea0c9a0384df69ed86a943a15cde37d0360b82491b3910dc2215e202e62b5b02 # via sphinx jinja2==3.1.6 \ --hash=sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d \ From 6100c28ca8181c9d6585e8ba3db112f59bcd042e Mon Sep 17 00:00:00 2001 From: Vitor Bandeira Date: Mon, 9 Nov 2026 10:22:16 -0300 Subject: [PATCH 3/3] docs: correct the pin comments and list uv Sphinx 9.1 itself caps docutils below 0.23, and sphinx-book-theme 1.4.0 needs pydata-sphinx-theme 0.20.0 exactly. The README now lists uv, which the lock regeneration step uses. Signed-off-by: Vitor Bandeira --- docs/README.md | 1 + docs/requirements.in | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index d9cfb562db..c032a9d6dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,6 +15,7 @@ repository and is published at The pinned Sphinx release needs Python 3.12 or newer. - `pip` - `virtualenv` (or the standard-library `venv`) +- `uv`, only to regenerate the lock file ### Install prerequisites diff --git a/docs/requirements.in b/docs/requirements.in index 15173f1274..56c28a5820 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,10 +1,11 @@ sphinx-external-toc==1.1.0 -# sphinx 9.2 and docutils 0.23 need Python 3.13; the docs build uses 3.12. +# Sphinx 9.2 needs Python 3.13 and the docs build uses 3.12. +# Sphinx 9.1 requires docutils <0.23. sphinx~=9.1.0 docutils>=0.22,<0.23 sphinx-autobuild myst-parser~=5.1.0 -# sphinx-book-theme 1.4.0 supports pydata-sphinx-theme 0.20.x. +# sphinx-book-theme 1.4.0 requires pydata-sphinx-theme 0.20.0 exactly. sphinx-book-theme==1.4.0 pydata-sphinx-theme==0.20.0 sphinx-copybutton