Upgrade Sphinx for 3.14 support; drop doc build support on 3.8; test 3.14#2112

EliahKagan

As detailed in d1ca2af and 8d97906, no version of Sphinx supports both Python 3.8 and Python 3.14. This makes changes analogous to those in #1954 and #1956, except to extend support to Python 3.14 (rather than Python 3.13), and the changes here are significantly simpler than what had to be done in #1954, since no Python code had to be changed in this case.

d1ca2af uses a newer Sphinx version range where supported. 8d97906 then requires that version range, thereby dropping the ability to build documentation on 3.8, and adjusting CI accordingly. I did these as separate steps, expressing the version conditionally in d1ca2af, so that we can restore the relevant files to how they were there in the unexpected event that it's necessary to continue supporting building documentation on Python 3.8.

This adds some more interpreters to be tested regularly. The main purpose of this is to test Python 3.14 on GNU/Linux and macOS, where it is currently expected to work. It is expected only to mostly work on Windows, for the same reason that Python 3.13 is also only expected to mostly work on Windows. In both cases, there is a test that will fail on Windows. This is still as described in #1955, except that I haven't yet updated that to note that the situation is now the same for--and that it will thus also be able to address--Python 3.14.

Another change made to the interpreters tested here is that this tests free-threaded interpreters not only on GNU/Linux but also on macOS. We might want to undo that if it makes CI take longer overall. I expect that to rarely or never happen, but I'm not sure. I might find out during the course of testing this PR, which I'm doing in multiple pushes, whether that's a problem. For some more details (and rationale) on the interpreters added to be tested, see d1ab2e4 and 53c0a88.

This remains a draft mainly because, while I know the documentaton builds, I want to look at the RTD docs to make sure they look okay--they should either look the same or slightly better due to the upgrade, but this shouldn't be assumed.

Edit: Here's the build, and here's what it looks like. It looks the same as before, which is as expected--I just wanted to make sure it was no worse. With the newer Sphinx, I suspect it may be easier to make it look better too, such as by looking at other themes that might make the content clearer, especially in the API reference. But that's not automatic, and it's definitely outside the scope of this PR.

The main remaning thing to check, beisdes that all CI jobs pass (they should actually all pass for each commit except 53c0a88) is that macOS isn't what keeps CI on the PR from completing sooner. If so, then we might consider going back to testing free-threaded builds only on Ubuntu and not macOS, since that would decrease the number of macOS jobs by 2.

Further edit: See comments for more updates on this.

EliahKagan

That, as of this writing, all the still-pending checks at the tip of this PR are for macOS is some reason to think I may have been too eager in thinking we can run more jobs on macOS without it increasing the total PR check time.

However, I think the much shorter time macOS checks take than Windows checks will still make this not a problem. I'll check to see if that's really the case before assuming the enw checks in this PR don't have to be pared down before this is ready to merge.

Edit: I guessed wrong! The slowness of the Windows checks is outmatched by the smaller number of available macOS runners! I suspect that the Tahoe runners might be even faster, by an amount that reverses that, but the case for testing free-threaded interprters on macOS is weak enough right now that I'll just go back to testing free-threaded interpreters only on GNU/Linux on CI.

Edit 2: I've removed them in a new commit rather than rebasing out the original commit that added them, since I think both the process of testing them as well as their results are valuable to have in the history. I think this PR can be merged once CI passes on this new commit.

Copilot

Pull request overview

This PR updates documentation build dependencies and CI configuration to accommodate Python 3.14 support, acknowledging that a single Sphinx version range can no longer support building docs on Python 3.8 while also supporting Python 3.14.

Changes:

Bump Sphinx requirement for documentation builds to a newer supported range (>=7.4.7,<8).
Extend CI test matrix to include Python 3.14 and 3.14 free-threaded (3.14t).
Adjust CI documentation-build gating intended to skip docs on Python 3.7 and 3.8.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File Description

doc/requirements.txt	Updates Sphinx version range used by the doc extra to a range compatible with Python 3.14.
.github/workflows/pythonpackage.yml	Extends the CI Python matrix and attempts to alter docs-build gating logic.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

EliahKagan added 4 commits March 9, 2026 16:07

EliahKagan requested a review from Copilot March 9, 2026 23:19

Copilot started reviewing on behalf of EliahKagan March 9, 2026 23:20 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

Comment thread .github/workflows/pythonpackage.yml Show resolved Hide resolved

Comment thread .github/workflows/pythonpackage.yml Show resolved Hide resolved

Comment thread .github/workflows/pythonpackage.yml Show resolved Hide resolved

EliahKagan marked this pull request as ready for review March 9, 2026 23:31

EliahKagan deleted the py314 branch March 9, 2026 23:32

EliahKagan requested a review from Copilot March 9, 2026 23:34

Copilot started reviewing on behalf of EliahKagan March 9, 2026 23:35 View session

This comment was marked as resolved.

Sign in to view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Upgrade Sphinx for 3.14 support; drop doc build support on 3.8; test 3.14#2112