Pin Sphinx plugins to compatible versions #1803

EliahKagan · 2024-01-15T22:34:16Z

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. Two of the plugins are pinned to ranges of a few versions rather than individual versions in order to preserve compatibility with Python 3.7 without making doc/requirements.txt more complicated (but Python 3.7 could be special-cased if desired, as discussed at the end of #1802). I also took this opportunity to bump the sphinx dependency to the latest bugfix release within 4.3, which does not break compatibility. I used whitespace in same style as in test-requirements.txt.

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:

fix: treeNotSorted issue #1799 (comment) (I believe this is where it was originally discovered.)
Sphinx doc builds recently fail on Python 3.9 and higher #1802 (Further details and analysis.)

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

This uses narrow ranges, rather than pinning single versions, for two of the Sphinx plugins whose versions are recently pinned. This is so that plugin versions compatible with Python 3.7 (which GitPython still supports) can be selected.

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.

Byron

Thanks so much for your help with this, and for keeping GitPython afloat!

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.

EliahKagan mentioned this pull request Jan 15, 2024

Sphinx doc builds recently fail on Python 3.9 and higher #1802

Closed

EliahKagan marked this pull request as ready for review January 15, 2024 22:39

EliahKagan mentioned this pull request Jan 15, 2024

fix: treeNotSorted issue #1799

Merged

Extend plugin version ranges down for Python 3.7

370822c

This uses narrow ranges, rather than pinning single versions, for two of the Sphinx plugins whose versions are recently pinned. This is so that plugin versions compatible with Python 3.7 (which GitPython still supports) can be selected.

EliahKagan force-pushed the sphinx branch from ecaad9d to 370822c Compare January 15, 2024 22:50

Bump Sphinx from 4.3.0 to 4.3.2

74ef6c7

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.

Byron approved these changes Jan 16, 2024

View reviewed changes

Byron merged commit 6978325 into gitpython-developers:main Jan 16, 2024
22 checks passed

EliahKagan deleted the sphinx branch January 16, 2024 08:00

EliahKagan mentioned this pull request Jan 19, 2024

Override bash executable, defaulting to Git for Windows git bash over WSL bash #1791

Open

EliahKagan mentioned this pull request Feb 23, 2024

Build online docs (RTD) with -W and dependencies #1843

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Pin Sphinx plugins to compatible versions #1803

Pin Sphinx plugins to compatible versions #1803

EliahKagan commented Jan 15, 2024 •

edited

Loading

Byron left a comment

Pin Sphinx plugins to compatible versions #1803

Pin Sphinx plugins to compatible versions #1803

Conversation

EliahKagan commented Jan 15, 2024 • edited Loading

Byron left a comment

Choose a reason for hiding this comment

EliahKagan commented Jan 15, 2024 •

edited

Loading