Sphinx doc builds recently fail on Python 3.9 and higher #1802
Comments
This fixes version incompatibilities with major version 4 of Sphinx, which GitPython is still using for the time being. Some plugins that previously had depended back on Sphinx have had those dependencies removed to avoid dependency cycles, but the effect is that `pip` no longer is aware of or able to enforce version compatibility, and newer plugin versions than can actually run with Sphinx 4 are installed instead of older, usable versions. This fixes the problem by pinning each of the affected Sphinx plugins' latest actually compatible versions, i.e., latest versions that do not need Sphinx 5 or higher. The alternative of moving to Sphinx 5 or higher should probably be done eventually, but will require addressing a cross-reference ambiguity in type annotations for the `Actor` class. For details on the bug, see: - gitpython-developers#1799 (comment) - gitpython-developers#1802
Although 4.4.0 or greater do not seem usable for the time being due to finding "more than one target found for cross-reference 'Actor'" as examined in gitpython-developers#1802, bugfixes from 4.3.* patch releases are okay.
|
Thanks so much for the detailed analysis! Somehow I feel that it's OK to keep the docs duct-taped into place and now with the version-pinning, I'd expect it to keep working for a while longer as well. The auto-generated docs that are having issues now never were desirable - they looked messy, were partial, and often the formatting is off as it's incredibly hard to get these RST doc-strings right. Even when I knew what I was looking for, I would have difficulty finding it and it was best to resort to a code-search. Maybe it's just me, but based on my experiences and unless Sphinx 5 yields significantly better docs for classes, including search, then it's probably not worth to invest anymore time than to keep it working. Also, I acknowledge that my writing might be affected as I seem to hold a grudge against it for breaking first the doc-builds on readthedocs and a little later, CI here, without any change of myself. With that said, it was running for what feels like a decade, so overall it's still a great job 😁. |
That could be investigated. In my mind, the main benefit of using a later version of Sphinx is that fewer issues like this would occur and, when they do, they could be reported as bugs against the relevant Sphinx package. Because Sphinx 4 is no longer supported, the effects of changes in Sphinx-related packages and their dependencies on it are, as I understand it, not generally being considered to be bugs. As far as I have found, there are no security advisories for any of the versions of Sphinx-related packages that GitPython is using. Taken together with the points you've raised, I think this suggests that the benefit of upgrading may be low at this time. The best thing to do may be to wait until GitPython drops support for Python 3.7 -- which when it happens should, I think, be for unrelated reasons -- and then revisit whether Sphinx can and should be upgraded. That would simplify some issues for development dependencies. |
|
That sounds good - let's revisit the upgrade to Sphinx 5 once doing so is potentially cheap as at the very least we can hope for another decade of 'it just works'. |
It occurs to me that it may be possible to fix that efficiently, with some information about intended style. (This is separate from what version of Sphinx is used.) For example, in #1725 I mentioned:
But that's actually feasible to search for (albeit imprecisely). So if it turns out that there is a simple pattern for what is intended, for example if a paragraph break in the rendered documentation is always or usually intended in such cases, then I think those improvements could be made without difficulty. Another example is the formatting of literals, especially
I'm wondering if that may already have improved, even by the version of Sphinx that GitPython is using. I am usually able to find classes and their methods by typing their name into the search box. This works for me on readthedocs as well as in local builds. (On the other hand, editor-based symbol lookup has also advanced, so the relative value of searching the documentation and search the code may have remained the same.) The aspect of the rendered API documentation that I find most confusing is the way the sections, as listed in the sidebar, are capitalized. This often differs from the capitalization of the identifiers they refer to or most closely relate to. |
|
I think if Sphinx 5 becomes an option and generally works, it might be worth trying to figure out how to configure it for best effect. Maybe by now Sphinx would suffer from the very old configuration and maybe plugins, and setting it up freshly might naturally bring forward great features. Currently the look also isn't to my liking, and I am sure there are great themes that would be a better fit if one took the time to evaluate and configure them. I am hopeful that in the end, the docs will look much better than I thought possible, maybe with not even that great of an effort. |
This configures Read the Docs builds to be more like local builds in two ways: - Pass "-W", as is done in a local build with "make -C doc html", so that if there are broken references, the build fails. - Install dependencies. This configures the Python environment, via the python.install key, so that RTD builds install requirements. More specifically on dependency installation, it does two things: 1. The equivalent of "pip install .", which installs the project and its dependencies (though not any extras). This includes the gitdb dependency, which is needed to import GitPython's git module to populate sections in the API Reference page (gitpython-developers#1840). 2. The equivalent of "pip install -r doc/requirements.txt", which installs the additional Sphinx-related dependencies used when building documentation locally. Installing Sphinx-related dependencies is useful for three reasons: a. Least importantly, it should increase consistency between remote (RTD) and local documentation builds. b. It may be needed to avoid warnings that are not being fixed at this time, while still allowing the build to succeed with the "-W" option (see above on that change) that causes failure for immediately addressable problems. The effect of newer versions of Sphinx carrying a few extra hard-to-fix warnings for GitPython is noted in gitpython-developers#1802 (and is why they are not upgraded in gitpython-developers#1803). c. One of the documentation build dependencies listed in doc/requirements.txt is sphinx_rtd_theme. In 634151a (for gitpython-developers#1794) the line specifying this theme was commented out, since it apparently broke in the build. This may allow it to be used again (or can be replaced with another custom theme if desired). This also reenables the sphinx_rtd_theme theme disabled in 634151a. Finally, this makes minor changes to .readthedocs.yml's comments and formatting so the comments are accurate for GitPython details and so the file is formatted in the same style as other YAML here.
This bug was discovered by @et-repositories in #1799. The problem was not introduced in that (currently unmerged) pull request. It affects all branches including the main branch. I've proposed a fix in #1803.
The bug
On Python 3.9 and higher, on all platforms, building the docs has begun to fail:
This has happened due to a change in indirect documentation build dependencies whose version numbers are not pinned. It is not due to any code change in GitPython (neither on the main branch nor in any open pull requests).
Analysis
The cause is:
doc/requirements.txtfile pins Sphinx at version 4.3.0.Sphinx>=5. No version of sphinxcontrib-applehelp since 1.0.5 is actually compatible with major version 4 of Sphinx.pipbe unaware that sphinxcontrib-applehelp 1.0.8 is not really compatible with Sphinx 4.3.0.Thus, running
pip install -r doc/requirements.txtnow installs both Sphinx 4.3.0 and sphinxcontrib-applehelp 1.0.8, even though they are not actually compatible with each other, and the error shown above occurs when attempting to build documentation.Note that, separately from the above, the latest version of sphinxcontrib-applehelp that supports Python 3.7 (which GitPython still supports) is sphinxcontrib-applehelp 1.0.2.
Other plugins are likewise affected
The first incompatibility to be identified and reported when running
make -C doc htmlis with sphinxcontrib-applehelp, and the build terminates immediately. But the problem is not specific to that one plugin. Instead, that plugin's name is alphabetically the earliest, of those that have recently gotten releases that remove the circular dependency. The affected plugins relevant to GitPython's documentation builds are:Can we upgrade Sphinx?
Sphinx 4 is quite old, and ideally GitPython would move to a later major version of Sphinx. However, this is not as simple as one might hope. Sphinx 5.0.0 and later will complain about ambiguities in documentation cross-references in more situations, or at least more situations than Sphinx 4.3.0. (As detailed below, this actually seems to start in Sphinx 4.4.0.)
That is a good thing, of course, because usually such ambiguities can be fixed easily, and doing so improves documentation. But it appears that GitPython has a particular kind of ambiguity that is difficult to fix without either making a breaking change or causing the documentation to become confusing.
This is the failure:
That is shown above with Sphinx 5.3.0, the latest version that supports all versions of Python that GitPython supports. But I also tested it on Sphinx 5.0.0, the lowest version compatible with recent versions of sphinxcontrib-applehelp and the other plugins noted above, with the same result.
What Sphinx 5 is talking about
GitPython has Sphinx treat warnings as errors by placing
-WinSPHINXOPTS, which is good since otherwise one risks building documentation whose text or cross-references are markedly different from what one expects. I recommend against removing or significantly weakening that. However, for testing purposes one can also pass--keep-goingto reveal the other warnings that would occur:Notwithstanding their inaccurate wording (possibly relating to interaction with sphinx-autodoc-typehints, I am not sure), these warnings are not actually issued for references in docstrings, but instead for references in type annotations. In
git.objects.tag.TagObject.__init__:GitPython/git/objects/tag.py
Line 47 in 53ddf38
In
git.index.base.IndexFile.commit:GitPython/git/index/base.py
Lines 1082 to 1083 in 53ddf38
I don't know if this is really a sufficient condition to cause the problem, but the reported ambiguity is between the
Actorclass ingit/util.py, and the very same class imported intogit/objects/util.pyand "exported" from it by listing it in__all__.Another ambiguity, possibly relevant
It seems like something more must be going on to cause the problem, since the imports, as a Python implementation must read them, import it from
git.util, which I believe is nevergit.objects.util. This is a strange statement to make; shouldn't I be sure? Well, this is hard to reason about, becausegit.utilalready refers to two separate modules:from git.util import X, thegit.utilmodule isgit/util.py, as one would expect.git.util, or a statement likeimport git.util, thegit.utilmodule isgit/index/util.py.This happens because
git/__init__.pyrebinds thegit.utilattribute:GitPython/git/__init__.py
Line 26 in 53ddf38
I think this should be fixed--so it does not do that--in the next major version of GitPython. But I don't think there's any reasonable way to fix it without a breaking change. The workaround is to always use
fromimports when accessing things in the originalgit.util. (A secondary workaround is to usesys.modules["git.util"], which always refers to the originalgit.util.) I also do not know if it is a contributing factor in confusing Sphinx about whoseutilmodule'sActoris being referred to.I note that issue here for two reasons. One is in case it turns out to be relevant in later investigation. The other is that, even if it is causally unrelated, it seems to exacerbate the problem that there are no completely elegant solutions, as detailed in "Possible fixes" below.
Versions between 4.3.0 and 5
GitPython currently pins Sphinx at 4.3.0, and this could be brought up to 4.3.2 without introducing warnings about the
Actorannotations.Sphinx also has versions 4.4.0 and 4.5.0. I believe they do not themselves introduce generally breaking changes. However, like the versions of Sphinx 5 I tested (5.0.0 and 5.3.0), they detect the
Actorannotation as ambiguous, failing in the same way. My guess is that this arises as an effect one one of the documented changes in 4.4.0, but I don't know which one or why.Is it Sphinx, or sphinx-autodoc-typehints?
The sphinx-autodoc-typehints plugin depends on specific versions of Sphinx, such that when Sphinx is upgraded, it must sometimes be upgraded. With Sphinx 4.3.0, sphinx-autodoc-typehints 1.17.1 is used. Later versions of sphinx-autodoc-typehints can be used with later versions of Sphinx. Even Sphinx 4.4.0 allows a later version to be installed.
So is it really newer versions than 4.3.0 of Sphinx that consider the
Actorannotation to be ambiguous, or is it the versions of sphinx-autodoc-typehints that comes with them?To test this, I pinned recently updated plugins (see below), then also pinned sphinx-autodoc-typehints at 1.17.1 and tried Sphinx 4.4.0 and Sphinx 4.5.0. The failures still occurred. So it is really Sphinx, or at least that is an important part of it. It seems very unlikely that pinning sphinx-autodoc-typehints could solve this.
Possible fixes
Import tweaks?
I have tried changing relative imports to absolute imports, moving imports out of
if TYPE_CHECKING:, and combinations of the two. None of that seems to make any difference. I didn't expect it to, but I figured it was worth a try.Importing
Actorfrom where it is re-exported?Actoris actually defined ingit/util.py. Ambiguities can often be overcome by making a reference more explicit as to what it means. But replacingActorwithgit.util.Actorwould not be an improvement. The ambiguity is in whatgit.utilrefers to, and at runtime,git.util.Actorwould always be resolved asgit.index.util.Actor, which we do not mean (and which I do not expect to exist).However,
git.objects.util.Actoris the same class, and it can be referred to explicitly. It may be possible to make the Sphinx build work with no warnings, and without suppressing any warnings that could cause serious problems in generated documentation to go undetected, by annotating it that way, possibly in combination with other tweaks.I am reluctant to do this. Conceptually, that's not where
Actoris from. As I understand it, it is offered throughgit.objects.utilfor convenience, not based on the idea that it ought really to have been defined there. Furthermore, I'm reluctant to make changes to Python code to get documentation to build, when the changes might make the code itself more confusing. After all, one of the ways the code is documented is the code itself.Exploring less compatible solutions?
Another possible general approach is to use the latest version of Sphinx, which only supports Python 3.9 and later, and see if there is a way to fix things up with that. I expect that to have the same problems, but I have not investigated this.
We can use different versions of Sphinx on different versions of Python, but the generated documentation may then differ. It is probably undesirable for the documentation to differ based on what version of Python we use to generate it, among versions GitPython documents support for.
Pinning or reconfiguring sphinx-autodoc-typehints?
As noted above, pinning sphinx-autodoc-typehints is unlikely to solve this, but perhaps the plugin can be reconfigured in such a way that little accuracy is lost overall but where
Actoris reported differently to Sphinx. I don't know how fruitful this would be.Pinning the recently updated plugins (#1803)
A more conservative solution, which should not preclude a better solution later, is to list sphinxcontrib-applehelp and the other affected plugins explicitly in
doc/requirements.txtand either:With the first approach, Python 3.7 support would have to be excluded (the documentation build step can be disabled on CI for Python 3.7), or Sphinx plugin dependency versions would have to be special-cased for Python 3.7, or versions compatible with Python 3.7 would have to be used on all Python versions.
The second approach avoids all that, but may make it harder for some automated tools to detect vulnerable versions, in the event that a security vulnerability is ever found and reported in any of these plugins. The second approach might also obscure what versions are actually known to work, but this could be minimized by specifying lower bounds (just low enough for Python 3.7 to have a compatible version) as well as upper bounds.
The 3.7 issue could also be avoided by dropping support for Python 3.7 (as the PSF has done). But since people who use GitPython (i.e., have it as a project dependency) don't generally build the documentation themselves, I don't recommend dropping 3.7 support for this reason.
Even with that Python 3.7 issue to deal with, this is a conceptually straightforward and fairly simple change, which does not require any Python code to be modified. I think it makes sense to do this first to get Sphinx builds working again on the main branch (and any PRs that rebase onto it), and then possibly pursue better solutions.
PR #1803 would fix the bug by pinning the plugins (addressing the Python 3.7 issue using the second approach, with lower as well as upper bounds on the two plugins that would otherwise not install on Python 3.7).
The text was updated successfully, but these errors were encountered: