Skip to content

docs: build with Python 3.12 and Sphinx 9.1 - #4809

Merged
vvbandeira merged 3 commits into
The-OpenROAD-Project:masterfrom
vvbandeira:docs-python-312
Nov 9, 2026
Merged

vvbandeira merged 3 commits into
The-OpenROAD-Project:masterfrom
vvbandeira:docs-python-312

Conversation

@vvbandeira

Copy link
Copy Markdown
Member

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:

  • 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

docs/requirements.in caps 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.py settings and toc.yml work without changes on these versions.
The Read the Docs preview of this PR is the check for the full build, including the llms.txt output and the theme layout.

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>
@vvbandeira
vvbandeira requested a review from a team as a code owner November 9, 2026 13:24
@vvbandeira
vvbandeira requested review from sombraSoft and removed request for a team November 9, 2026 13:24

@gemini-code-assist gemini-code-assist Bot left a comment

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.

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.

Comment thread docs/README.md
Comment on lines +14 to +15
- 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.

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.

@openroad-ci

Copy link
Copy Markdown
Member

🔍 QoR check

Metrics reflect the PR merge build — i.e. what will land on the target branch.

Commit f809f47 · Jenkins build #1 · Baseline: build · View build on dashboard

62 design(s) checked — 0 with regression(s), 0 without a comparable baseline.

@vvbandeira
vvbandeira merged commit 2ccdcd3 into The-OpenROAD-Project:master Nov 9, 2026
12 checks passed
@vvbandeira
vvbandeira deleted the docs-python-312 branch November 9, 2026 17:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants