Drop support for Sphinx<5 (#220)

* Drop support for Sphinx<5 I'm matching the plan with `sphinx_rtd_theme` to reduce maintainers work. * Implementation updates * Require Sphinx>=5 * Update documentation dependencies * Test on more Python versions * Remove Python 2.7 support * Update Read the Docs config * Use Tox<4 * Make all tests to run successfully - Support for Sphinx 7.2.x - Modify some part of the code from AA-Turner commits - Update tests to make all of them work * Update Read the Docs config * Remove deprecated configs * Update docs * Drop support for docutils < 0.17 * Remove code for deprecated settings * Update docs * Remove pytest ignores * Python 3.12 is not ready yet * Remove `notfound_no_urls_prefix` check * End with slash * Remove test for `no_prefix_urls` which is deprecated * `title=` check on Sphinx 5, 6, 7 * Update checks for Sphinx versions on tests * Fix Python 3.9 issue with typing --------- Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
readthedocs · Aug 24, 2023 · dcb3adc · dcb3adc
1 parent b7b9d5e
commit dcb3adc
Show file tree

Hide file tree

Showing 14 changed files with 240 additions and 632 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -8,10 +8,12 @@ commands:
         type: string
       sphinx-version:
         type: string
-        default: "1,2,3,4,5,latest"
+        default: "5,6,7,latest"
     steps:
       - checkout
-      - run: pip install --user tox
+      # NOTE: use Tox 3.x until I understand the syntax for generative environments:
+      # https://tox.wiki/en/stable/user_guide.html#generative-environment-list
+      - run: pip install --user "tox<4"
       - run: tox -e "<<parameters.version>>-sphinx{<<parameters.sphinx-version>>}"
 
 jobs:
@@ -33,12 +35,15 @@ jobs:
     steps:
       - run-tox:
           version: py310
-          # Do not run tests for Python 3.10 and Sphinx3 because it's broken
-          # See https://github.com/sphinx-doc/sphinx/issues/9816
-          sphinx-version: '1,2,4,5,latest'
+  py311:
+    docker:
+      - image: 'cimg/python:3.11'
+    steps:
+      - run-tox:
+          version: py311
   docs:
     docker:
-      - image: 'cimg/python:3.10'
+      - image: 'cimg/python:3.11'
     steps:
       - checkout
       - run: pip install --user tox
@@ -49,6 +54,7 @@ workflows:
   tests:
     jobs:
       - docs
+      - py311
       - py310
       - py39
       - py38
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,7 +1,11 @@
 version: 2
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
 python:
-  version: 3
   install:
     - method: pip
       path: .

diff --git a/docs/conf.py b/docs/conf.py
@@ -31,9 +31,7 @@
 
 # -- General configuration ---------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+needs_sphinx = '5.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -42,7 +40,6 @@
     'notfound.extension',
     'autoapi.extension',
     'sphinx_tabs.tabs',
-    'sphinx-prompt',
     'sphinxemoji.sphinxemoji',
 ]
 
@@ -66,17 +63,13 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
-
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -48,7 +48,9 @@ For other use cases, you can customize these configuration options in your ``con
 
    Prefix added to all the URLs generated in the 404 page.
 
-   Default: ``'/en/latest/'``
+   Default: ``'/<language>/<version>/'`` where ``<language>`` is ``READTHEDOCS_LANGUAGE`` environment variable
+            and ``<version>`` is ``READTHEDOCS_VERSION`` environment variable.
+            In case these variables are not defined, it defaults to ``/en/latest/``.
 
    Type: string
 
@@ -60,54 +62,3 @@ For other use cases, you can customize these configuration options in your ``con
    .. tip::
 
       The prefix can be completely removed by setting it to ``None``.
-
-.. confval:: notfound_default_language
-
-   Language used as default to generate all links to the resources.
-
-   Default: :envvar:`READTHEDOCS_LANGUAGE` environment variable, if set, else ``'en'``
-
-   Type: string
-
-   .. note::
-
-      All links generated will have this prefix (e.g. ``/en/``).
-      This setting works with ``notfound_default_version`` to create a prefix for all URLs.
-
-   .. deprecated:: 0.5
-
-      ``notfound_default_language`` is deprecated.  Use :confval:`notfound_urls_prefix` instead
-
-.. confval:: notfound_default_version
-
-   Version used as default to generate all links to the resources.
-
-   Default: :envvar:`READTHEDOCS_VERSION` environment variable, if set, else ``'latest'``
-
-   Type: string
-
-   .. note::
-
-      All links generated will have this prefix (e.g. ``/latest/``).
-      This setting works with ``notfound_default_language`` to create a prefix for all URLs.
-
-   .. deprecated:: 0.5
-
-      ``notfound_default_version`` is deprecated.  Use :confval:`notfound_urls_prefix` instead
-
-.. confval:: notfound_no_urls_prefix
-
-   URL prefixes skipped or included.
-
-   Default: ``False``.
-
-   Type: bool
-
-   .. note::
-
-      If this option is set to ``True``, the extension omits any prefix values from the URLs,
-      including explicit values for ``notfound_default_language`` and ``notfound_default_version``.
-
-   .. deprecated:: 0.5
-
-      ``notfound_no_urls_prefix`` is deprecated.  Use :confval:`notfound_urls_prefix` instead
diff --git a/docs/how-it-works.rst b/docs/how-it-works.rst
@@ -41,8 +41,13 @@ html-page-context
 ~~~~~~~~~~~~~~~~~
 
 Immediately before the template is rendered with the context, this event is emitted.
-At this point, we override ``pathto`` [#pathto]_ function with our custom one that will generate the proper URLs.
-We also override ``toctree`` [#toctree]_ key with the same content of the regular toctree but with all the URLs fixed to find the resources from the 404 page.
+At this point, we override:
 
-.. [#pathto] https://www.sphinx-doc.org/page/templating.html#pathto
-.. [#toctree] https://www.sphinx-doc.org/page/templating.html#toctree
+* ``pathto`` [#pathto]_ function with our custom one that will generate the proper URLs.
+* ``toctree`` [#toctree]_ key with the same content of the regular toctree but with all the URLs fixed to find the resources from the 404 page.
+* ``js_tag`` [#js_tag]_ and ``css_tag`` [#css_tag]_ functions with the exact same code but using our own ``pathto``.
+
+.. [#pathto] https://www.sphinx-doc.org/page/development/templating.html#pathto
+.. [#toctree] https://www.sphinx-doc.org/page/development/templating.html#toctree
+.. [#js_tag] https://github.com/sphinx-doc/sphinx/blob/v7.2.2/sphinx/builders/html/__init__.py#L1057C1-L1068C1
+.. [#css_tag] https://github.com/sphinx-doc/sphinx/blob/v7.2.2/sphinx/builders/html/__init__.py#L1069C1-L1095C1
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -7,15 +7,15 @@ Install the package
 
    .. tab:: from PyPI
 
-      .. prompt:: bash
+      .. code:: console
 
-         pip install sphinx-notfound-page
+         $ pip install sphinx-notfound-page
 
    .. tab:: from GitHub
 
-      .. prompt:: bash
+      .. code:: console
 
-         pip install git+https://github.com/readthedocs/sphinx-notfound-page
+         $ pip install "sphinx-notfound-page @ git+https://github.com/readthedocs/sphinx-notfound-page"
 
 
 Once we have the package installed,

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,86 +4,85 @@
 #
 #    pip-compile --extra=doc --output-file=docs/requirements.txt pyproject.toml
 #
-alabaster==0.7.12
+alabaster==0.7.13
     # via sphinx
-astroid==2.12.2
+anyascii==0.3.2
     # via sphinx-autoapi
-babel==2.10.3
+astroid==2.15.6
+    # via sphinx-autoapi
+babel==2.12.1
     # via sphinx
-certifi==2022.6.15
+certifi==2023.7.22
     # via requests
-charset-normalizer==2.1.0
+charset-normalizer==3.2.0
     # via requests
-docutils==0.17.1
+docutils==0.18.1
     # via
     #   sphinx
     #   sphinx-rtd-theme
     #   sphinx-tabs
-idna==3.3
+idna==3.4
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.2
     # via
     #   sphinx
     #   sphinx-autoapi
-lazy-object-proxy==1.7.1
+lazy-object-proxy==1.9.0
     # via astroid
-markupsafe==2.1.1
+markupsafe==2.1.3
     # via jinja2
-packaging==21.3
+packaging==23.1
     # via sphinx
-pygments==2.12.0
+pygments==2.16.1
     # via
     #   sphinx
-    #   sphinx-prompt
     #   sphinx-tabs
-pyparsing==3.0.9
-    # via packaging
-pytz==2022.1
-    # via babel
-pyyaml==6.0
+pyyaml==6.0.1
     # via sphinx-autoapi
-requests==2.28.1
+requests==2.31.0
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==4.5.0
+sphinx==7.2.3
     # via
     #   sphinx-autoapi
-    #   sphinx-notfound-page
     #   sphinx-notfound-page (pyproject.toml)
-    #   sphinx-prompt
     #   sphinx-rtd-theme
     #   sphinx-tabs
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
     #   sphinxemoji
-sphinx-autoapi==1.8.4
-    # via sphinx-notfound-page (pyproject.toml)
-sphinx-notfound-page==0.8.3
-    # via sphinx-notfound-page (pyproject.toml)
-sphinx-prompt==1.5.0
+sphinx-autoapi==2.1.1
     # via sphinx-notfound-page (pyproject.toml)
-sphinx-rtd-theme==1.0.0
+sphinx-rtd-theme==1.3.0
     # via sphinx-notfound-page (pyproject.toml)
-sphinx-tabs==3.3.1
+sphinx-tabs==3.4.1
     # via sphinx-notfound-page (pyproject.toml)
-sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-applehelp==1.0.7
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.5
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-htmlhelp==2.0.4
     # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.6
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.9
     # via sphinx
 sphinxemoji==0.2.0
     # via sphinx-notfound-page (pyproject.toml)
-unidecode==1.3.4
-    # via sphinx-autoapi
-urllib3==1.26.10
+typing-extensions==4.7.1
+    # via astroid
+urllib3==2.0.4
     # via requests
-wrapt==1.14.1
+wrapt==1.15.0
     # via astroid