Skip to content

Upgrade Sphinx docs toolchain (6.2.1 → 8.1.3)#2165

Open
ChihweiLHBird wants to merge 1 commit into
apache:trunkfrom
ChihweiLHBird:zhiwei/upgrade-sphinx
Open

Upgrade Sphinx docs toolchain (6.2.1 → 8.1.3)#2165
ChihweiLHBird wants to merge 1 commit into
apache:trunkfrom
ChihweiLHBird:zhiwei/upgrade-sphinx

Conversation

@ChihweiLHBird

@ChihweiLHBird ChihweiLHBird commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

Upgrade Sphinx docs toolchain (6.2.1 → 8.1.3)

What

Modernize the docs dependency group and sync the lockfile:

Package Before After
sphinx 6.2.1 8.1.3
sphinx_rtd_theme 2.0.0 3.1.0
docutils (transitive) 0.19 0.21.2
jinja2 (unpinned) >=3.1.6
pygments >=2.20.0,<3.0.0 unchanged

Why

  • sphinx==6.2.1 cannot run on Python 3.12+ (ast.Str, removed in 3.12), blocking local doc builds on modern interpreters.
  • 8.1.3 is the newest Sphinx that still supports the project's minimum Python (3.10), so requires-python is unchanged.
  • sphinx_rtd_theme==3.1.0 supports Sphinx 6–9 and constrains docutils<0.23.

Changes

  • pyproject.toml — bump the docs group as above.
  • uv.lock — regenerated to match (RTD/CI use uv sync --frozen, which fails on a stale lock).
  • .readthedocs.yml — removed the obsolete note about pinning an older Sphinx to fix bullet-point rendering. That was a sphinx_rtd_theme < 1.0 / docutils >= 0.17 issue, long fixed in the current theme.

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.39%. Comparing base (2ec566d) to head (83c6948).

Additional details and impacted files
@@           Coverage Diff           @@
##            trunk    #2165   +/-   ##
=======================================
  Coverage   83.39%   83.39%           
=======================================
  Files         351      351           
  Lines       81476    81476           
  Branches     8746     8746           
=======================================
  Hits        67940    67940           
  Misses      10744    10744           
  Partials     2792     2792           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ChihweiLHBird
ChihweiLHBird marked this pull request as draft July 21, 2026 03:46
@ChihweiLHBird

ChihweiLHBird commented Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Wait, there's a v8.2.3, let me try that version Never mind, v8.2 doesn't support Python 3.10

@ChihweiLHBird
ChihweiLHBird marked this pull request as ready for review July 21, 2026 13:45
@ChihweiLHBird
ChihweiLHBird marked this pull request as draft July 21, 2026 13:46
Signed-off-by: Zhiwei Liang <zhiwei.liang@zliang.me>
@ChihweiLHBird
ChihweiLHBird force-pushed the zhiwei/upgrade-sphinx branch from 656053c to 4e1a1cd Compare July 21, 2026 13:54
@ChihweiLHBird
ChihweiLHBird marked this pull request as ready for review July 21, 2026 13:54
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