Upgrade Sphinx to ~7.4.7

EliahKagan · EliahKagan · commit d1ca2af85b96 · 2026-03-09T17:58:11.000-04:00
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 #1954, which upgraded Sphinx to 7.1.2 on all Python versions GitPython suppports other than Python 3.7. The subsequent change in #1956 of removing support for building the GitPython documentation on Python 3.7 may be paralleled for 3.8 shortly.
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,3 +1,4 @@
-sphinx >= 7.1.2, < 7.2
+sphinx >= 7.4.7, < 8 ; python_version >= "3.9"
+sphinx >= 7.1.2, < 7.2 ; python_version < "3.9"
 sphinx_rtd_theme
 sphinx-autodoc-typehints
