Runtime verification of sphinx and jinja2 versions

.github/workflows/test.yml

@@ -23,16 +23,20 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Setup environment
-        run: |
-          python -m venv venv
-          source venv/bin/activate
-
-      - name: Install
         run: |
           python -m pip install --upgrade pip wheel setuptools
           python -m pip install -r requirements/test.txt -r doc/requirements.txt
           python -m pip install codecov
           python -m pip install ${{ matrix.sphinx-version }}
+          python -m pip list
+
+      - name: Downgrade Jinja2 for sphinx<4
+        if: (${{ matrix.sphinx-version }} == 'sphinx==1.8.0') ||
+          (${{ matrix.sphinx-version }} == 'sphinx==2.1')
+        run: python -m pip install jinja2==3.0.3
+
+      - name: Install
+        run: |
           python -m pip install .
           pip list
 

numpydoc/__init__.py

@@ -5,6 +5,31 @@
 __version__ = '1.2.2.dev0'
 
 
+def _verify_sphinx_jinja():
+    """Ensure sphinx and jinja versions are compatible.
+
+    Jinja2>=3.1 requires Sphinx>=4.0.2. Raises exception if this condition is
+    not met.
+
+    TODO: This check can be removed when the minimum supported sphinx version
+    for numpydoc sphinx>=4.0.2
+    """
+    import sphinx, jinja2
+    from packaging import version
+
+    if version.parse(sphinx.__version__) <= version.parse("4.0.2"):
+        if version.parse(jinja2.__version__) >= version.parse("3.1"):
+            from sphinx.errors import VersionRequirementError
+            raise VersionRequirementError(
+                "\n\nSphinx<4.0.2 is incompatible with Jinja2>=3.1.\n"
+                "If you wish to continue using sphinx<4.0.2 you need to pin "
+                "Jinja2<3.1."
+            )
+
+
+_verify_sphinx_jinja()
+
+
 def setup(app, *args, **kwargs):
     from .numpydoc import setup
     return setup(app, *args, **kwargs)

setup.py

@@ -43,7 +43,7 @@ def read(fname):
     author_email="[email protected]",
     url="https://numpydoc.readthedocs.io",
     license="BSD",
-    install_requires=["sphinx>=1.8", 'Jinja2>=2.10,<3.1'],
+    install_requires=["sphinx>=1.8", 'Jinja2>=2.10'],
     python_requires=">=3.7",
     extras_require={
         "testing": [