Upgrade Sphinx for 3.14 support; drop doc build support on 3.8; test 3.14#2112
Merged
EliahKagan merged 5 commits intogitpython-developers:mainfrom Mar 9, 2026
Merged
Upgrade Sphinx for 3.14 support; drop doc build support on 3.8; test 3.14#2112EliahKagan merged 5 commits intogitpython-developers:mainfrom
EliahKagan merged 5 commits intogitpython-developers:mainfrom
Conversation
As discussed in gitpython-developers#2005 and gitpython-developers#2011, we had not been doing this before. Conditions have changed in two relevant ways: - The free-threaded interpreter has been around longer and it sees more use. - The macOS runners are very fast now. The specific motivations for doing this now are: - In view of the condition described in gitpython-developers#2109 and how the change there seems to have helped with it, there's some reason to think *patch* versions of Python sometimes affect GitPython in ways it makes possibly unfounded assumptions about the effect of garbage collection. This mainly affects Windows and it is not specific to free-threaded builds. However, in principle we could also see assumptions violated in tests we think always work on Unix-like operating systems, due to differences in how garbage collection works in free-threaded interpreters. Therefore, the assumption that this only needs to be tested occasionally is not as well founded I assumed when I suggested testing it only on GNU/Linux. - We may add 3.14 jobs to CI soon, and it's useful to be able to see how both free-threaded interpreters work on CI, as well as to confirm for at least a short while that they are continuing to work as expected. This macOS free-threaded interpreter CI jobs could be disabled once more if necessary, or if they're found to make CI complete slower in PRs by even a small amount so long as they don't seem to be surfacing anything.
The status of 3.14 is now effectively the same as the status of 3.13 when we started testing it in gitpython-developers#1990. This doesn't enable it on Windows yet, for the same reason that we still have not yet enabled regular CI tests of 3.13 on Windows. It is hoped that 3.13 and 3.14 can be gotten fully working on Windows (rather than just mostly working, we think) soon; these exclusions are meant to be temporary. Both the usual GIL interpreter and the free-threaded (nogil) intepreters are tested. See the immediately preceding commit on the tradeoffs involved in doing so.
Except on Python 3.8, where 7.1.2 is the latest compatible version.
(This would also apply to versions lower than 3.8, but we don't
support building docs on any such versions, even though we still
support installing and using GitPython on 3.7.)
The reason for this change is that, starting in Python 3.14, the
`ast` module no longer has a `Str` member. String literals are
instead represented by `ast.Constant` (and the type of the value
can be checked to see if it's a string). But versions of `sphinx`
lower than 7.2.0 rely on `ast.Str` being present. This causes our
documentation not to be able to build at all starting in 3.14. The
most important part of the error is:
Exception occurred:
File "/opt/hostedtoolcache/Python/3.14.3/x64/lib/python3.14/site-packages/sphinx/pycode/__init__.py", line 141, in analyze
raise PycodeError(f'parsing {self.srcname!r} failed: {exc!r}') from exc
sphinx.errors.PycodeError: parsing '/home/runner/work/GitPython/GitPython/git/index/base.py' failed: AttributeError("module 'ast' has no attribute 'Str'")
An example of code in `sphinx` 7.1.2 that will cause such an error
is `sphinx.pycode.parser.visit_Expr` implementation, which starts:
if (isinstance(self.previous, (ast.Assign, ast.AnnAssign)) and
isinstance(node.value, ast.Str)):
In `sphinx` 7.2.0, `sphinx.pycode.parser.visit_Expr` instead
begins:
if (isinstance(self.previous, (ast.Assign, ast.AnnAssign)) and
isinstance(node.value, ast.Constant) and isinstance(node.value.value, str)):
This upgrades `sphinx` on all versions of Python where it *can* be
installed at a version that has such changes -- rather than only on
Python 3.14 -- for consistency, including consistency in possible
minor variations in generated documentation that could otherwise
arise from using different versions of `sphinx` unnecessarily.
As for why this upgrades to 7.4.7 rather than only to 7.2.0, that's
because they are both compatible with the same versions of Python,
and as far as I know there's no reason to prefer an earlier version
within that range.
Although GitPython still supports being installed and run on Python
3.8 (and even on Python 3.7), it has been end-of-life (i.e., no
longer supported by the Python Software Foundation) for quite some
time now. That the version of Sphinx used to build documentation
will now be different on Python 3.8 than other versions is a reason
not to use Python 3.8 for this purpose, but probablly already not
the most important reason.
The change here is conceptually similar to, but much simpler than,
the change in gitpython-developers#1954, which upgraded Sphinx to 7.1.2 on all Python
versions GitPython suppports other than Python 3.7. The subsequent
change in gitpython-developers#1956 of removing support for building the GitPython
documentation on Python 3.7 may be paralleled for 3.8 shortly.
This discontinues supporting building documentation on Python 3.8. It does not affect installing or running GitPython on Python 3.8 (except when the `doc` extra is used, but this is only used for building documentation). The reason is that it is no longer possible to use the same version of Sphinx on Python 3.8 as on the most recent supported versions of Python, because Python 3.14 no longer has `ast.Str` (using `str.Constant` for string literals instead), which causes the oldest version of `sphinx` that runs on Python 3.14 to be `sphinx` 7.2.0, while the newest version that is installable on Python 3.8 is `sphinx` 7.1.2. The immediately preceding commit changes the requirements for the `doc` extra to specify a newer `sphinx` version for Python 3.9 and later. This can't be done on Python 3.8. Because there can be subtle differences in documentation generated with different `sphinx` versions, and because Python 3.8 has been end-of-life for some time, it is not really worth carrying conditional dependencies for the `sphinx` version in `doc/requirements.txt`. Note that, while it is probably not a very good idea to use GitPython (or anything) on Python 3.8 since it is end-of-life, this change does not stop supporting installing GitPython on that or any other version it has been supporting. Installing and using GitPython remains supported all the way back to Python 3.7 at this time. This only affects the `doc` extra and its requirements. This change is analogous to the change made in gitpython-developers#1956, which followed up on the change in gitpython-developers#1964 in the same way this change follows up on the change in the immediately preceding commit.
Member
Author
This effectively reverts d1ab2e4. It doesn't look like any problems arose, and contrary to my guess, the additional jobs do actually make the checks that we intend to be blocking for PRs take longer, even after all non-macOS checks have completed.
Contributor
There was a problem hiding this comment.
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.
This comment was marked as resolved.
This comment was marked as resolved.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

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.