Upgrade Sphinx for 3.14 support; drop doc build support on 3.8; test 3.14 by EliahKagan · Pull Request #2112 · gitpython-developers/GitPython

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.