Merge pull request #57 from saimn/sphinx-minversion

Updates for recent Sphinx versions

Author: saimn

.github/workflows/python-tests.yml

@@ -17,30 +17,24 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: ubuntu-latest
-            python-version: 3.7
-            toxenv: py37-test-sphinx17
           - os: windows-latest
             python-version: 3.7
-            toxenv: py37-test-sphinx18
-          - os: macos-latest
-            python-version: 3.7
-            toxenv: py37-test-sphinx20
-          - os: ubuntu-latest
-            python-version: 3.8
-            toxenv: py38-test-sphinx24
-          - os: windows-latest
-            python-version: 3.8
             toxenv: py38-test-sphinx30
           - os: ubuntu-latest
-            python-version: 3.9
-            toxenv: py39-test-sphinx35
+            python-version: 3.8
+            toxenv: py38-test-sphinx35
           - os: ubuntu-latest
             python-version: 3.9
             toxenv: py39-test-sphinx40
+          - os: ubuntu-latest
+            python-version: "3.10"
+            toxenv: py310-test-sphinx50
+          - os: ubuntu-latest
+            python-version: "3.11"
+            toxenv: py311-test-sphinx60
           - os: macos-latest
-            python-version: 3.9
-            toxenv: py39-test-sphinxdev
+            python-version: "3.11"
+            toxenv: py311-test-sphinxdev
 
     steps:
     - uses: actions/checkout@v2
@@ -54,11 +48,3 @@ jobs:
       run: python -m pip install tox
     - name: Run Tox
       run: tox -v -e ${{ matrix.toxenv }}
-
-    # - name: Slack Notification
-    #   uses: 8398a7/action-slack@v3
-    #   with:
-    #     status: ${{ job.status }}
-    #   env:
-    #     SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
-    #   if: always() # TODO: cron

CHANGES.rst

@@ -4,6 +4,10 @@ Changes in sphinx-astropy
 1.9 (unreleased)
 ----------------
 
+- Update minimum required version of Sphinx to 3.0.0. [#57]
+
+- ``check_sphinx_version`` is deprecated. [#57]
+
 1.8 (2023-01-06)
 ----------------
 

setup.cfg

@@ -20,7 +20,7 @@ packages = find:
 python_requires = >=3.7
 install_requires =
     packaging
-    sphinx>=1.7
+    sphinx>=3.0.0
     astropy-sphinx-theme
     numpydoc
     sphinx-automodapi

sphinx_astropy/conf/v1.py

@@ -12,11 +12,9 @@
 import os
 import warnings
 from collections import ChainMap
-
 from os import path
 
-import sphinx
-from packaging.version import Version
+import astropy_sphinx_theme
 
 try:
     import astropy
@@ -34,21 +32,15 @@
 # minor parts of the version number, not the micro.  To do a more
 # specific version check, call check_sphinx_version("x.y.z.") from
 # your project's conf.py
-needs_sphinx = '1.7'
+needs_sphinx = '3.0'
 
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 
 def check_sphinx_version(expected_version):
-    sphinx_version = Version(sphinx.__version__)
-    expected_version = Version(expected_version)
-    if sphinx_version < expected_version:
-        raise RuntimeError(
-            "At least Sphinx version {0} is required to build this "
-            "documentation.  Found {1}.".format(
-                expected_version, sphinx_version))
-
+    warnings.warn("check_sphinx_version is deprecated, use needs_sphinx instead",
+                  DeprecationWarning)
 
 # Configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
@@ -64,7 +56,8 @@ def check_sphinx_version(expected_version):
     'matplotlib': ('https://matplotlib.org/stable/',
                    (None, 'http://data.astropy.org/intersphinx/matplotlib.inv')),
     'astropy': ('https://docs.astropy.org/en/stable/', None),
-    'h5py': ('https://docs.h5py.org/en/stable/', None)}
+    'h5py': ('https://docs.h5py.org/en/stable/', None),
+}
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -199,22 +192,24 @@ def check_sphinx_version(expected_version):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx_astropy.ext.intersphinx_toggle',
-              'sphinx.ext.autodoc',
-              'sphinx.ext.intersphinx',
-              'sphinx.ext.todo',
-              'sphinx.ext.coverage',
-              'sphinx.ext.inheritance_diagram',
-              'sphinx.ext.viewcode',
-              'sphinxcontrib.jquery',
-              'numpydoc',
-              'sphinx_automodapi.automodapi',
-              'sphinx_automodapi.smart_resolver',
-              'sphinx_astropy.ext.changelog_links',
-              'sphinx_astropy.ext.generate_config',
-              'sphinx_astropy.ext.missing_static',
-              'sphinx.ext.mathjax',
-              'pytest_doctestplus.sphinx.doctestplus']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'sphinxcontrib.jquery',
+    'numpydoc',
+    'pytest_doctestplus.sphinx.doctestplus',
+    'sphinx_astropy.ext.changelog_links',
+    'sphinx_astropy.ext.generate_config',
+    'sphinx_astropy.ext.intersphinx_toggle',
+    'sphinx_astropy.ext.missing_static',
+    'sphinx_automodapi.automodapi',
+    'sphinx_automodapi.smart_resolver',
+]
 
 try:
     import matplotlib.sphinxext.plot_directive
@@ -248,7 +243,7 @@ def check_sphinx_version(expected_version):
     '-Efontsize=10',
     '-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif',
     '-Gfontsize=10',
-    '-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif'
+    '-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif',
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -270,7 +265,6 @@ def check_sphinx_version(expected_version):
 # pixels large.
 
 # We include by default the favicon that is in the bootstrap-astropy theme.
-import astropy_sphinx_theme
 html_theme_path = astropy_sphinx_theme.get_html_theme_path()
 html_favicon = os.path.join(html_theme_path[0], html_theme, 'static', 'astropy_logo.ico')
 

sphinx_astropy/ext/__init__.py

@@ -1,2 +1 @@
-from __future__ import division, absolute_import, print_function
 

sphinx_astropy/ext/changelog_links.py

@@ -4,8 +4,6 @@
 GitHub issues.
 """
 
-from __future__ import print_function
-
 import re
 from docutils.nodes import Text, reference
 

sphinx_astropy/ext/intersphinx_toggle.py

@@ -9,18 +9,12 @@
 
 This is used e.g. by astropy-helpers when using the build_docs command.
 """
-from packaging.version import Version
 
-from sphinx import __version__
-
-SPHINX_LT_18 = Version(__version__) < Version('1.8')
+from sphinx.util.console import bold
+from sphinx.util import logging
 
 
 def disable_intersphinx(app, config=None):
-
-    from sphinx.util.console import bold
-
-    from sphinx.util import logging
     info = logging.getLogger(__name__).info
 
     if app.config.disable_intersphinx:
@@ -29,16 +23,7 @@ def disable_intersphinx(app, config=None):
 
 
 def setup(app):
-
-    # Note that the config-inited setting was only added in Sphinx 1.8. For
-    # earlier versions we use builder-inited but we need to be careful in what
-    # order the extensions are declared so that this happens before intersphinx.
-    if SPHINX_LT_18:
-        app.connect('builder-inited', disable_intersphinx)
-    else:
-        app.connect('config-inited', disable_intersphinx)
-
+    app.connect('config-inited', disable_intersphinx)
     app.add_config_value('disable_intersphinx', 0, True)
-
     return {'parallel_read_safe': True,
             'parallel_write_safe': True}

sphinx_astropy/ext/missing_static.py

@@ -5,12 +5,7 @@
 a static directory to be present but it isn't.
 """
 import os
-from packaging.version import Version
-
-from sphinx import __version__
-
-SPHINX_LT_18 = Version(__version__) < Version('1.8')
-
+from sphinx.util import logging
 
 WARNING_TEMPLATE = """
 Note: The static directory '{0}' was not found. This is often because it is
@@ -22,8 +17,6 @@
 
 
 def static_warning(app, config=None):
-
-    from sphinx.util import logging
     info = logging.getLogger(__name__).info
 
     for directory in app.config.html_static_path:
@@ -32,7 +25,6 @@ def static_warning(app, config=None):
 
 
 def setup(app):
-
     app.connect('build-finished', static_warning)
 
     return {'parallel_read_safe': True,

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 envlist =
-    py{37,38,39}-test
+    py{37,38,39,310,311}-test
     codestyle
 requires =
     setuptools >= 30.3.0
@@ -12,22 +12,14 @@ changedir = .tmp/{envname}
 description = run tests
 extras = tests
 deps =
-    sphinx17: sphinx==1.7.*
-    sphinx17: Jinja2==3.0.3
-    sphinx18: sphinx==1.8.*
-    sphinx18: Jinja2==3.0.3
-    sphinx20: sphinx==2.0.*
-    sphinx20: docutils==0.17.*
-    sphinx20: Jinja2==3.0.3
-    sphinx24: sphinx==2.4.*
-    sphinx24: docutils==0.17.*
-    sphinx24: Jinja2==3.0.3
     sphinx30: sphinx==3.0.*
     sphinx30: docutils==0.17.*
     sphinx30: Jinja2==3.0.3
     sphinx35: sphinx==3.5.*
     sphinx35: Jinja2==3.0.3
     sphinx40: sphinx==4.0.*
+    sphinx50: sphinx==5.0.*
+    sphinx60: sphinx==6.0.*
     sphinxdev: git+https://github.com/sphinx-doc/sphinx#egg=sphinx
 
 commands =