Repository navigation
docs: build with Python 3.12 and Sphinx 9.1 - #4809
Conversation
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 <vvbandeira@precisioninno.com>
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 <vvbandeira@precisioninno.com>
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 <vvbandeira@precisioninno.com>
There was a problem hiding this comment.
Code Review
This pull request updates the Read the Docs build environment to Ubuntu 24.04 and Python 3.12, upgrading Sphinx to version 9.1.0 along with other documentation dependencies, and switches the lock file generation tool from pip-compile to uv. The review feedback points out a technical inaccuracy in the updated docs/README.md regarding Sphinx 9.1's Python version requirements and provides a suggestion to clarify that while Sphinx 9.1 supports Python 3.10 or newer, Python 3.12 is recommended to match the build environment.
| - 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. |
There was a problem hiding this comment.
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.
| - 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. |
🔍 QoR checkMetrics reflect the PR merge build — i.e. what will land on the target branch. Commit 62 design(s) checked — 0 with regression(s), 0 without a comparable baseline. |
Read the Docs builds the ORFS documentation with Python 3.10 and Sphinx 5.3.
Sphinx 9.1 needs Python 3.12, and so do current releases of other Python packages in this repo, such as numpy 2.5.
This PR is the first step toward letting the Dependabot Python group (#4784) pass.
It moves the docs build to Python 3.12 on ubuntu-24.04 and regenerates the hash-pinned docs lock with uv.
Main version changes:
docs/requirements.incaps Sphinx at 9.1, because Sphinx 9.2 needs Python 3.13.The docs README now names Python 3.12 and gives the uv command to regenerate the lock.
The
conf.pysettings andtoc.ymlwork without changes on these versions.The Read the Docs preview of this PR is the check for the full build, including the
llms.txtoutput and the theme layout.