Repository navigation
Commit d1ca2af
committed
Upgrade Sphinx to ~7.4.7
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.1 parent 53c0a88 commit d1ca2af
1 file changed
Lines changed: 2 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1,3 +1,4 @@ | |||
| 1 | - sphinx >= 7.1.2, < 7.2 | ||
| 1 | + sphinx >= 7.4.7, < 8 ; python_version >= "3.9" | ||
| 2 | + sphinx >= 7.1.2, < 7.2 ; python_version < "3.9" | ||
| 2 | 3 | sphinx_rtd_theme | |
| 3 | 4 | sphinx-autodoc-typehints | |
0 commit comments