Pass includehidden= as string instead of boolean

Sphinx 7.2 changed its internal API for `toctree()`. See https://github.com/sphinx-doc/sphinx/issues/11607 Related https://github.com/readthedocs/sphinx_rtd_theme/issues/1463
2026-10-15 10:52:01 -05:00 · 2023-08-17 14:04:56 +02:00
15 changed files with 331 additions and 147 deletions
@@ -11,14 +11,10 @@ commands:
        type: string
      sphinx-version:
        type: string
-        default: "latest"
+        default: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest"
    steps:
      - checkout
-      # We cannot upgrade to Tox4 because running generative environments doesn't work.
-      # I guess it has changed its syntax or similar.
-      #   $ tox run -e "py310-sphinx{50,51}"
-      #   ROOT: HandledError| provided environments not found in configuration file: ['51}']
-      - run: pip install --user 'tox~=3.27'
+      - run: pip install --user tox~=3.27
      - run: tox -e "<<parameters.version>>-sphinx{<<parameters.sphinx-version>>}"
  run-build:
    description: "Ensure built assets are up to date"
@@ -44,48 +40,53 @@ jobs:
      - image: 'cimg/python:3.9-node'
    steps:
      - run-build: {}
+  py27:
+    docker:
+      - image: 'cimg/python:2.7'
+    steps:
+      - run-tox:
+          version: py27
+          sphinx-version: "17,18"
  py36:
    docker:
      - image: 'cimg/python:3.6'
    steps:
      - run-tox:
          version: py36
-          sphinx-version: "50,51,52,53"
  py37:
    docker:
      - image: 'cimg/python:3.7'
    steps:
      - run-tox:
          version: py37
-          sphinx-version: "50,51,52,53"
  py38:
    docker:
      - image: 'cimg/python:3.8'
    steps:
      - run-tox:
          version: py38
-          sphinx-version: "50,51,52,53,60,61,62,70,71,latest"
+          sphinx-version: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,60,latest"
  py39:
    docker:
      - image: 'cimg/python:3.9'
    steps:
      - run-tox:
          version: py39
-          sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest"
+          sphinx-version: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,60,latest"
  py310:
    docker:
      - image: 'cimg/python:3.10'
    steps:
      - run-tox:
          version: py310
-          sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest"
+          sphinx-version: "42,43,44,45,50,51,52,53,60,latest"
  py311:
    docker:
      - image: 'cimg/python:3.11'
    steps:
      - run-tox:
          version: py311
-          sphinx-version: "53,60,61,62,70,71,72,latest,dev"
+          sphinx-version: "53,60,latest"

 workflows:
  version: 2
@@ -110,3 +111,6 @@ workflows:
      - py36:
          requires:
            - build
+      - py27:
+          requires:
+            - build
@@ -1,11 +1,7 @@
 version: 2

-build:
-  os: "ubuntu-22.04"
-  tools:
-    python: "3.10"
-
 python:
+  version: 3.8
  install:
    - requirements: docs/requirements.txt
    - method: pip
@@ -4,31 +4,12 @@ Changelog

 .. seealso:: :ref:`howto_upgrade`

-.. |theme_version| replace:: 2.0.0rc2
-
-.. _release-2.0.0:
-
-2.0.0rc2
-========
-
-Added
-----
-
-* Support for docutils ``<=0.20``
-
-Deprecations
------------
-
-* The HTML4 writer is now officially deprecated. An error will be thrown if your
-  project configuration still uses the HTML4 writer.
-* Support for Sphinx versions < 5.0 was removed.
-* In addition, our supported dependencies will match the dependencies from our
-  lowest supported Sphinx release, version 5.0: Python >= 3.6 and docutils > 0.14 and < 0.19
+.. |theme_version| replace:: 1.3.0rc2

 .. _release-1.3.0:

-1.3.0
-=====
+1.3.0rc1
+========

 Added
 -----
@@ -103,18 +103,20 @@ compatibility.

 The following cases need to be tested with changes to CSS or JavaScript:

-* Multiple, modern browsers should be tested.
-* Multiple viewport sizes should be tested for changes.
-  We support large, tablet, and mobile viewport sizes
-* We currently support only HTML5 writer.
-* Multiple major versions of Sphinx should be tested.
-  We currently support Sphinx ``>=5.0``
+* Multiple, modern browsers should be tested. We officially support back
+  to IE11 at the moment
+* Multiple viewport sizes should be tested for changes. We support large,
+  tablet, and mobile viewport sizes
+* We currently support both the Sphinx HTML4 writer and HTML5 writer. This makes
+  for some complex CSS selectors
+* Multiple major versions of Sphinx should be tested. We currently support back
+  to Sphinx version ``1.6``

 It's easiest to test combinations of dependency versions using ``tox``:

 .. code:: console

-    % tox -e py310-sphinx62
+    % tox -e py3-sphinx34-html4

 If the tests and build are successful, you can view the built documentation at
 the directory noted by Sphinx:
@@ -123,9 +125,9 @@ the directory noted by Sphinx:

    build succeeded, 10 warnings.

-    The HTML pages are in .tox/py310-sphinx62/tmp/html.
+    The HTML pages are in .tox/py3-sphinx34-html4/tmp/html.
    ___________________________ summary ___________________________
-      py310-sphinx62: commands succeeded
+      py3-sphinx34-html4: commands succeeded
      congratulations :)

 You can then open up this path with a series of browsers to test.
@@ -135,12 +137,12 @@ multiple ``tox`` environments, and open both up for comparison:

 .. code:: console

-    % tox -e py310-sphinx62
+    % tox -e py3-sphinx34-html4
    ...
-    % tox -e py310-sphinx53
+    % tox -e py3-sphinx34-html5
    ...
-    % firefox .tox/py310-sphinx62/tmp/html/index.html
-    % firefox .tox/py310-sphinx53/tmp/html/index.html
+    % firefox .tox/py3-sphinx34-html4/tmp/html/index.html
+    % firefox .tox/py3-sphinx34-html5/tmp/html/index.html

 You can also use a separate ``tox`` environment for building output to compare
 against. All of the ``tox`` environments have an additional postfix, ``-qa``, to
@@ -153,25 +155,28 @@ For example, to test against the tag ``0.5.2``:
 .. code:: console

    % git checkout 0.5.2
-    % tox -e py310-sphinx53-qa
+    % tox -e py3-sphinx34-html4-qa
    ...
    % git checkout feature/example-pull-request
-    % tox -e py310-sphinx53
+    % tox -e py3-sphinx34-html4
    ...
-    % firefox .tox/py310-sphinx53-qa/tmp/html/index.html
-    % firefox .tox/py310-sphinx53/tmp/html/index.html
+    % firefox .tox/py3-sphinx34-html4-qa/tmp/html/index.html
+    % firefox .tox/py3-sphinx34-html4/tmp/html/index.html

 Currently, the most important environments to QA are:

 .. This list is purposely shorter than what we describe above. If we test all of
-   the cases above, we'll be here all day. Python 3, and latest
+   the cases above, we'll be here all day. Python 3, HTML4/5 writer, and latest
   minor of each major Sphinx release should give us enough work.

-* ``py310-sphinx53``
-* ``py310-sphinx62``
-* ``py310-sphinx72``
-* ``py310-sphinxlatest``
-* ``py310-sphinxdev``
+* ``py3-sphinx18-html4``
+* ``py3-sphinx18-html5``
+* ``py3-sphinx24-html4``
+* ``py3-sphinx24-html5``
+* ``py3-sphinx35-html4``
+* ``py3-sphinx35-html5``
+* ``py3-sphinx41-html4``
+* ``py3-sphinx41-html5``

 Translations
 ============
@@ -7,11 +7,19 @@ API documentation and generated content
 :mod:`test_py_module`
 =====================

-.. automodule:: test_py_module.test
-    :members:
-    :private-members:
-    :special-members:
+.. only:: python3

+    .. automodule:: test_py_module.test
+        :members:
+        :private-members:
+        :special-members:
+
+.. only:: python2
+
+    .. automodule:: test_py_module.test_py27
+        :members:
+        :private-members:
+        :special-members:

 C++ API
 =======
@@ -145,8 +153,18 @@ Sphinx Extensions
 sphinx.ext.autosummary
 ----------------------

-.. autosummary::
+.. only:: python3

-    test_py_module.test.add_numbers
-    test_py_module.test.subtract_numbers
-    test_py_module.test.Foo
+    .. autosummary::
+
+        test_py_module.test.add_numbers
+        test_py_module.test.subtract_numbers
+        test_py_module.test.Foo
+
+.. only:: python2
+
+    .. autosummary::
+
+        test_py_module.test_py27.add_numbers
+        test_py_module.test_py27.subtract_numbers
+        test_py_module.test_py27.Foo
@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+"""
+This module will overwrite test.py for Python 2.7 builds.
+Type signatures cause autodoc to break in Python 2.7 documentation builds, so they are removed here.
+
+Test Module for sphinx_rtd_theme."""
+
+
+class Foo:
+
+    """Docstring for class Foo.
+
+    This text tests for the formatting of docstrings generated from output
+    ``sphinx.ext.autodoc``. Which contain reST, but sphinx nests it in the
+    ``<dl>``, and ``<dt>`` tags. Also, ``<tt>`` is used for class, method names
+    and etc, but those will *always* have the ``.descname`` or
+    ``.descclassname`` class.
+
+    Term
+        It is also possible to include definitions inside docstrings.
+        They should be styled as a normal definition list.
+
+    :Field List:
+        It is also possible to include definitions inside docstrings.
+        They should be styled as a normal definition list.
+
+    .. [1] A footnote contains body elements, consistently indented by at
+       least 3 spaces.
+
+    .. [Citation] A citation contains body elements, consistently indented by at
+       least 3 spaces.
+
+    Normal ``<tt>`` (like the <tt> I just wrote here) needs to be shown with
+    the same style as anything else with ````this type of markup````.
+
+    It's common for programmers to give a code example inside of their
+    docstring::
+
+        from test_py_module import Foo
+
+        myclass = Foo()
+        myclass.dothismethod('with this argument')
+        myclass.flush()
+
+        print(myclass)
+
+
+    Here is a link to :py:meth:`capitalize`.
+    Here is a link to :py:meth:`__init__`.
+
+    """
+
+    #: Doc comment for class attribute Foo.bar.
+    #: It can have multiple lines.
+    bar = 1
+
+    flox = 1.5   #: Doc comment for Foo.flox. One line only.
+
+    baz = 2
+    """Docstring for class attribute Foo.baz."""
+
+    def __init__(self, qux, spam=False):
+        """Start the Foo.
+
+        :param qux: The first argument to initialize class.
+        :type qux: string
+        :param spam: Spam me yes or no...
+        :type spam: bool
+
+        """
+        #: Doc comment for instance attribute qux.
+        self.qux = 3
+
+        self.spam = 4
+        """Docstring for instance attribute spam."""
+
+    def add(self, val1, val2):
+        """Return the added values.
+
+        :param val1: First number to add.
+        :type val1: int
+        :param val2: Second number to add.
+        :type val2: int
+        :rtype: int
+
+        The parameters of this method are described in the parameter list.
+        """
+
+        return val1 + val2
+
+    def capitalize(self, myvalue):
+        """Return a string as uppercase.
+
+        :param myvalue: String to change
+        :type myvalue: string
+        :rtype: string
+
+        """
+
+        return myvalue.upper()
+
+    def another_function(self, a, b, **kwargs):
+        """
+        Here is another function.
+
+        :param a: The number of green hats you own.
+        :type a: int
+
+        :param b: The number of non-green hats you own.
+        :type b: int
+
+        :param kwargs: Additional keyword arguments. Each keyword parameter
+                       should specify the name of your favorite cuisine.
+                       The values should be floats, specifying the mean price
+                       of your favorite dish in that cooking style.
+        :type kwargs: float
+
+        :returns: A 2-tuple.  The first element is the mean price of all dishes
+                  across cuisines.  The second element is the total number of
+                  hats you own: :math:`a + b`.
+        :rtype: tuple
+
+        :raises ValueError: When ``a`` is not an integer.
+
+        .. versionadded:: 1.0
+            This was added in 1.0
+        .. versionchanged:: 2.0
+            This was changed in 2.0
+        .. deprecated:: 3.0
+            This is deprecated since 3.0
+        """
+        return sum(kwargs.values()) / len(kwargs), a + b
+
+
+def add_numbers(a, b):
+    """Add two numbers together
+
+    :param a: The first number
+    :param b: The second number
+
+    Here is some more text.
+    """
+    return a + b
+
+
+def subtract_numbers(a, b):
+    """Subtract two numbers
+
+    :param a: The first number
+    :param b: The second number
+    """
+    return a - b
@@ -42,7 +42,7 @@ Internet Explorer (any OS, versions <=10)

 Internet Explorer (any OS, version 11)
    We currently only partially support IE11, and only test for major bugs.
-    Support will be removed in the :ref:`roadmap-release-3.0.0` release.
+    Support will be removed in the :ref:`roadmap-release-2.0.0` release.

 Opera (any OS, any version)
    **Community support only.** We do not receive enough traffic with this
@@ -62,20 +62,11 @@ The theme officially supports the following dependencies in your Sphinx project:
    * - Dependency
      - Versions
    * - Python
-      - 3.6 or greater
+      - 2.7 or 3.6 or greater
    * - Sphinx
-      - 5 or greater
+      - 1.7 up to at least 4.1
    * - docutils
-      - >= 0.14, < 0.19
-
-.. deprecated:: 2.0
-    Sphinx < 5 support removed
-
-.. deprecated:: 2.0
-    Python < 3.6 support removed
-
-.. deprecated:: 2.0
-    docutils < 0.14 support removed
+      - Up to 0.17

 .. versionadded:: 1.0
    Sphinx 4.0 support added
@@ -152,14 +143,15 @@ like Sphinx 1.8, HTML4, or required support for IE11.
 2.0.0
 ~~~~~

-:Planned release date: 2023 Q3
+:Planned release date: 2022 Q1

-This release will drop support for old Python and Sphinx versions.
+This release will mark the beginning of a new round of feature development, as
+well as a number of backward incompatible changes and deprecations.

-Note the following backwards incompatible changes are planned for this
+Of note, the following backwards incompatible changes are planned for this
 release:

-Python < 3.6, Sphinx < 5 and Docutils < 0.14 will not be tested
+Sphinx 1.x, Sphinx 2.x, and Docutils 0.16 will not be tested
    Official support will drop for these version, though they may still continue
    to work. Theme developers will not be testing these versions any longer.

@@ -168,7 +160,7 @@ HTML4 support will be removed
    and builds attempting to use the HTML4 writer will fail. If you are still
    using the HTML4 writer, or have the ``html4_writer = True`` option in your
    Sphinx configuration file, you will need to either remove this option or pin
-    your dependency to ``sphinx_rtd_theme<=3`` until you can.
+    your dependency to ``sphinx_rtd_theme<=2.0.0`` until you can.

    This option was suggested in the past to work around issues with HTML5
    support and should no longer be required to use a modern combination of this
@@ -179,31 +171,10 @@ HTML4 support will be removed
 3.0.0
 ~~~~~

-:Planned release date: 2024 Q1
-
-This release is not yet fully planned.
-However, we already know that we will be dropping support for older version of different dependencies and browsers.
-
-Sphinx 5, Python < 3.8 and docutils < 0.18 support will be removed
-    Sphinx 5 is the latest version that supports Python 3.6 and 3.7,
-    and docutils < 0.18.
-
-Internet Explorer 11 support will be dropped
-    `IE11 reached end of life on 14 June 20222 <https://endoflife.date/internet-explorer>`_,
-    so we are not supporting it on newer versions,
-    starting on 3.0.0.
-
-.. _roadmap-release-4.0.0:
-
-4.0.0
-~~~~~
-
-:Planned release date: 2024 Q2
-
-This release is not yet planned.
-There are plans to potentially replace Wyrm with Bootstrap in a release after 3.0.
+This release is not yet planned, however there are plans to potentially replace
+Wyrm with Bootstrap in a release after 2.0.

 Also tentatively planned for this release is finally removing built CSS and
 JavaScript assets from our repository. This will remove the ability to install
 the package directly from GitHub, and instead users will be advised to install
-development releases from PyPI.
+development releases from PyPI
@@ -58,3 +58,21 @@ Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1.
    
    More information is available in Read the Docs' documentation on :doc:`rtd:guides/reproducible-builds`.

+
+Via Git or Download
+-------------------
+
+.. warning::
+
+   Installing directly from the repository source is deprecated and is not
+   recommended. Static assets won't be included in the repository starting in
+   release :ref:`roadmap-release-3.0.0`.
+
+Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
+``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
+``conf.py`` file:
+
+.. code:: python
+
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = ["_themes", ]
@@ -1,6 +1,6 @@
 {
  "name": "sphinx_rtd_theme",
-  "version": "2.0.0rc2",
+  "version": "1.3.0rc1",
  "lockfileVersion": 1,
  "requires": true,
  "dependencies": {
@@ -1,7 +1,7 @@
 {
  "name": "sphinx_rtd_theme",
  "main": "js/theme.js",
-  "version": "2.0.0rc2",
+  "version": "1.3.0rc2",
  "scripts": {
    "dev": "webpack-dev-server --open --config webpack.dev.js",
    "build": "webpack --config webpack.prod.js",
@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.0.0rc2
+current_version = 1.3.0rc2
 commit = false
 tag = false
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)((?P<release>[a-z]+)(?P<dev>\d+))?
@@ -27,8 +27,8 @@ classifiers =
 	Environment :: Console
 	Environment :: Web Environment
 	Intended Audience :: Developers
+	Programming Language :: Python :: 2.7
 	Programming Language :: Python :: 3
-	Programming Language :: Python :: 3 :: Only
 	Programming Language :: Python :: 3.6
 	Programming Language :: Python :: 3.7
 	Programming Language :: Python :: 3.8
@@ -43,10 +43,10 @@ classifiers =
 include_package_data = True
 zip_safe = False
 packages = sphinx_rtd_theme
-python_requires = >=3.6
+python_requires = >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*
 install_requires = 
-	sphinx >=5,<8
-	docutils <0.21
+	sphinx >=1.6,<8
+	docutils <0.19
 	sphinxcontrib-jquery >=4,<5
 tests_require = 
 	pytest
@@ -86,7 +86,7 @@ class TransifexCommand(distutils.cmd.Command):


 setup(
-    version='2.0.0rc2',
+    version='1.3.0rc2',
    cmdclass={
        'update_translations': UpdateTranslationsCommand,
        'transifex': TransifexCommand,
@@ -12,7 +12,7 @@ from sphinx.locale import _
 from sphinx.util.logging import getLogger


-__version__ = '2.0.0rc2'
+__version__ = '1.3.0rc2'
 __version_full__ = __version__

 logger = getLogger(__name__)
@@ -40,11 +40,15 @@ def extend_html_context(app, pagename, templatename, context, doctree):
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
    if python_version[0] < 3:
-        logger.error("Python 2 is not supported with sphinx_rtd_theme, update to Python 3.")
-
-    app.require_sphinx('5.0')
-    if app.config.html4_writer:
-        logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")
+        logger.warning("Python 2 is deprecated with sphinx_rtd_theme, update to Python 3")
+    app.require_sphinx('1.6')
+    if sphinx_version <= (2, 0, 0):
+        logger.warning("Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater")
+        if not app.config.html_experimental_html5_writer:
+            logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")
+    else:
+        if app.config.html4_writer:
+            logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme")

    # Since Sphinx 6, jquery isn't bundled anymore and we need to ensure that
    # the sphinxcontrib-jquery extension is enabled.
@@ -62,14 +66,18 @@ def setup(app):
    # Register the theme that can be referenced without adding a theme path
    app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))

-    # Add Sphinx message catalog for newer versions of Sphinx
-    # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
-    rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
-    app.add_message_catalog('sphinx', rtd_locale_path)
-    app.connect('config-inited', config_initiated)
+    if sphinx_version >= (1, 8, 0):
+        # Add Sphinx message catalog for newer versions of Sphinx
+        # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
+        rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
+        app.add_message_catalog('sphinx', rtd_locale_path)
+        app.connect('config-inited', config_initiated)

    # sphinx emits the permalink icon for headers, so choose one more in keeping with our theme
-    app.config.html_permalinks_icon = "\uf0c1"
+    if sphinx_version >= (3, 5, 0):
+        app.config.html_permalinks_icon = "\uf0c1"
+    else:
+        app.config.html_add_permalinks = "\uf0c1"

    # Extend the default context when rendering the templates.
    app.connect("html-page-context", extend_html_context)
@@ -14,7 +14,7 @@
 {%- set sphinx_version_info = (_ver_major, _ver_minor, -1) -%}

 <!DOCTYPE html>
-<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
+<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
 <head>
  <meta charset="utf-8" />
  {{- metatags }}
@@ -29,11 +29,15 @@
    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
  {%- endif %}
  {%- for css in css_files %}
-    {{ css_tag(css) }}
+    {%- if css|attr("rel") %}
+      <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
+    {%- else %}
+      <link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
+    {%- endif %}
  {%- endfor %}

  {%- for cssfile in extra_css_files %}
-    {{ css_tag(cssfile) }}
+    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
  {%- endfor -%}

  {#- FAVICON
@@ -163,7 +167,7 @@
          {%- block menu %}
            {%- set toctree = toctree(maxdepth=theme_navigation_depth|int,
                                      collapse=theme_collapse_navigation|tobool,
-                                      includehidden=theme_includehidden|tobool,
+                                      includehidden=theme_includehidden,
                                      titles_only=theme_titles_only|tobool) %}
            {%- if toctree %}
              {{ toctree }}
@@ -1,10 +1,14 @@
 [tox]
 envlist =
-    py{36,37,38,39,310}-sphinx{50,51,52,53}{-qa}
-    py{38,39,310}-sphinx{60,61,62,70,71}{-qa}
-    py{39,310}-sphinx{72,latest,dev}{-qa}
+    # Python 2.7 support was removed in Sphinx 2
+    py{27}-sphinx{17,18}{-html4,-html5,}{-qa,}
+    py{36,37,38,39}-sphinx{18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52}{-html4,-html5,}{-qa,}
+    # Python 3.10 working from Sphinx 4.2 and up
+    py{310}-sphinx{42,43,44,45,50,51,52,53,latest}{-html4,-html5}{-qa,}
+    # Sphinx 6+ has simplified docutils and Python support
+    py{38,39,10}-sphinx{60,61,70,71}{-html5,}{-qa,}
    # Python 3.11 working from Sphinx 5.3 and up
-    py{311}-sphinx{53,60,61,62,70,71,72,latest,dev}{-qa}
+    py{311}-sphinx{53,60,61,70,71,latest}{html5}{-qa,}

 [testenv]
 setenv =
@@ -13,21 +17,44 @@ deps =
    .
    readthedocs-sphinx-ext
    pytest
+    sphinx17: Sphinx>=1.7,<1.8
+    sphinx18: Sphinx>=1.8,<1.9
+    sphinx20: Sphinx>=2.0,<2.1
+    sphinx21: Sphinx>=2.1,<2.2
+    sphinx22: Sphinx>=2.2,<2.3
+    sphinx23: Sphinx>=2.3,<2.4
+    sphinx24: Sphinx>=2.4,<2.5
+    sphinx30: Sphinx>=3.0,<3.1
+    sphinx31: Sphinx>=3.1,<3.2
+    sphinx32: Sphinx>=3.2,<3.3
+    sphinx33: Sphinx>=3.3,<3.4
+    sphinx34: Sphinx>=3.4,<3.5
+    sphinx35: Sphinx>=3.5,<3.6
+    sphinx40: Sphinx>=4.0,<4.1
+    sphinx41: Sphinx>=4.1,<4.2
+    sphinx42: Sphinx>=4.2,<4.3
+    sphinx43: Sphinx>=4.3,<4.4
+    sphinx44: Sphinx>=4.4,<4.5
+    sphinx45: Sphinx>=4.5,<4.6
    sphinx50: Sphinx>=5.0,<5.1
    sphinx51: Sphinx>=5.1,<5.2
    sphinx52: Sphinx>=5.2,<5.3
    sphinx53: Sphinx>=5.3,<5.4
    sphinx60: Sphinx>=6.0,<6.1
    sphinx61: Sphinx>=6.1,<6.2
-    sphinx62: Sphinx>=6.2,<6.3
    sphinx70: Sphinx>=7.0,<7.1
    sphinx71: Sphinx>=7.1,<7.2
-    sphinx72: Sphinx>=7.2,<7.3
+    # All these Sphinx versions actually break since docutils 0.18, so we need to add this upper bound
+    # Projects using these Sphinx versions will have to do the same
+    # See: https://github.com/readthedocs/sphinx_rtd_theme/pull/1304
+    sphinx{17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42}: docutils<0.18
+    # External environments are required to add this dependency for older versions of Sphinx
+    # because it didn't ship with this upper bound.
+    # See: https://github.com/sphinx-doc/sphinx/issues/10291
+    sphinx{17,18,20,21,22,23,24,30,31,32,33,34,35,40}: Jinja2<3.1
    sphinxlatest: Sphinx
-    dev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
-allowlist_externals =
-    echo
+    sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
 commands =
    pytest {posargs} tests/
-    sphinx-build -b html -Dhtml4_writer=0 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html
-    echo "Open the following URL for visual testing: file://{envtmpdir}/html/demo/demo.html"
+    !html4: sphinx-build -b html -Dhtml4_writer=0 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html
+    html4: sphinx-build -b html -Dhtml4_writer=1 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html