Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
9 changes: 5 additions & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,11 @@ 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.
Comment on lines +14 to +15

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The statement that the pinned Sphinx release (Sphinx 9.1) needs Python 3.12 or newer is technically incorrect. Sphinx 9.1 supports Python 3.10 or newer. However, using Python 3.12 is recommended to match the Read the Docs build environment.

Suggested change
- 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.
- Python 3.12 or newer — Read the Docs builds with 3.12 (see .readthedocs.yaml).
The pinned Sphinx release supports Python 3.10 or newer, but Python 3.12 is recommended to match the build environment.

- `pip`
- `virtualenv` (or the standard-library `venv`)
- `uv`, only to regenerate the lock file

### Install prerequisites

Expand All @@ -29,10 +30,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
Expand Down
13 changes: 9 additions & 4 deletions docs/requirements.in
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
sphinx-external-toc==0.3.1
sphinx
sphinx-external-toc==1.1.0
# 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
sphinx-book-theme
myst-parser~=5.1.0
# 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
sphinxcontrib-mermaid
sphinx-llm
118 changes: 60 additions & 58 deletions docs/requirements_lock.txt
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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 \
Expand Down Expand Up @@ -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
Expand All @@ -195,20 +188,21 @@ 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 \
--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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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 \
Expand All @@ -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
Expand Down Expand Up @@ -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 \
Expand All @@ -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 \
Expand Down