2.0 milestone: drop supported versions (#1500)

* 2.0 milestone: drop supported versions

The new policy is:

- Python >=3.6
- Sphinx >= 5
- HTML4 and HTML5 writer
- docutils >= 0.14, < 0.19

* Update roadmap after discussion

By the beginning of 2024 we should support newer Sphinx versions and HTML5 only.

* Remove Python 2.7 from CircleCI

* Run only supported versions on Python 3.11

* Update with feedback from review

* Update documentation to match our support

* Add Sphinx 6.2 that was missing

* Update tox/circleci to work

* Revert tox command

* Drop support for HTML4 and keep `-qa` testing

- drop support for HTML4 on 2.0
- keep `-qa` TOX environment to be able to compare feature branches
- emit `logger.errors` on Python 2 and html_writer4=True
- require Sphinx >= 5.0
- remove logic for old Sphinx versions

* Update Tox and CircleCI

* Update contributing page to match our plans

---------

Co-authored-by: Anthony Johnson <aj@ohess.org>

.circleci/config.yml

@@ -11,10 +11,14 @@ commands:
         type: string
       sphinx-version:
         type: string
-        default: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest"
+        default: "latest"
     steps:
       - checkout
-      - run: pip install --user tox~=3.27
+      # 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: tox -e "<<parameters.version>>-sphinx{<<parameters.sphinx-version>>}"
   run-build:
     description: "Ensure built assets are up to date"
@@ -40,53 +44,48 @@ 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: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,60,latest"
+          sphinx-version: "50,51,52,53,60,61,62,70,71,latest"
   py39:
     docker:
       - image: 'cimg/python:3.9'
     steps:
       - run-tox:
           version: py39
-          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"
+          sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest"
   py310:
     docker:
       - image: 'cimg/python:3.10'
     steps:
       - run-tox:
           version: py310
-          sphinx-version: "42,43,44,45,50,51,52,53,60,latest"
+          sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest"
   py311:
     docker:
       - image: 'cimg/python:3.11'
     steps:
       - run-tox:
           version: py311
-          sphinx-version: "53,60,latest"
+          sphinx-version: "53,60,61,62,70,71,72,latest,dev"
 
 workflows:
   version: 2
@@ -111,6 +110,3 @@ workflows:
       - py36:
           requires:
             - build
-      - py27:
-          requires:
-            - build

docs/contributing.rst

@@ -103,20 +103,18 @@ compatibility.
 
 The following cases need to be tested with changes to CSS or JavaScript:
 
-* Multiple, modern browsers should be tested. We officially support back
+* Multiple, modern browsers should be tested.
-  to IE11 at the moment
+* Multiple viewport sizes should be tested for changes.
-* Multiple viewport sizes should be tested for changes. We support large,
+  We support large, tablet, and mobile viewport sizes
-  tablet, and mobile viewport sizes
+* We currently support only HTML5 writer.
-* We currently support both the Sphinx HTML4 writer and HTML5 writer. This makes
+* Multiple major versions of Sphinx should be tested.
-  for some complex CSS selectors
+  We currently support Sphinx ``>=5.0``
-* 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 py3-sphinx34-html4
+    % tox -e py310-sphinx62
 
 If the tests and build are successful, you can view the built documentation at
 the directory noted by Sphinx:
@@ -125,9 +123,9 @@ the directory noted by Sphinx:
 
     build succeeded, 10 warnings.
 
-    The HTML pages are in .tox/py3-sphinx34-html4/tmp/html.
+    The HTML pages are in .tox/py310-sphinx62/tmp/html.
     ___________________________ summary ___________________________
-      py3-sphinx34-html4: commands succeeded
+      py310-sphinx62: commands succeeded
       congratulations :)
 
 You can then open up this path with a series of browsers to test.
@@ -137,12 +135,12 @@ multiple ``tox`` environments, and open both up for comparison:
 
 .. code:: console
 
-    % tox -e py3-sphinx34-html4
+    % tox -e py310-sphinx62
     ...
-    % tox -e py3-sphinx34-html5
+    % tox -e py310-sphinx53
     ...
-    % firefox .tox/py3-sphinx34-html4/tmp/html/index.html
+    % firefox .tox/py310-sphinx62/tmp/html/index.html
-    % firefox .tox/py3-sphinx34-html5/tmp/html/index.html
+    % firefox .tox/py310-sphinx53/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
@@ -155,28 +153,25 @@ For example, to test against the tag ``0.5.2``:
 .. code:: console
 
     % git checkout 0.5.2
-    % tox -e py3-sphinx34-html4-qa
+    % tox -e py310-sphinx53-qa
     ...
     % git checkout feature/example-pull-request
-    % tox -e py3-sphinx34-html4
+    % tox -e py310-sphinx53
     ...
-    % firefox .tox/py3-sphinx34-html4-qa/tmp/html/index.html
+    % firefox .tox/py310-sphinx53-qa/tmp/html/index.html
-    % firefox .tox/py3-sphinx34-html4/tmp/html/index.html
+    % firefox .tox/py310-sphinx53/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, HTML4/5 writer, and latest
+   the cases above, we'll be here all day. Python 3, and latest
    minor of each major Sphinx release should give us enough work.
 
-* ``py3-sphinx18-html4``
+* ``py310-sphinx53``
-* ``py3-sphinx18-html5``
+* ``py310-sphinx62``
-* ``py3-sphinx24-html4``
+* ``py310-sphinx72``
-* ``py3-sphinx24-html5``
+* ``py310-sphinxlatest``
-* ``py3-sphinx35-html4``
+* ``py310-sphinxdev``
-* ``py3-sphinx35-html5``
-* ``py3-sphinx41-html4``
-* ``py3-sphinx41-html5``
 
 Translations
 ============

docs/development.rst

@@ -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-2.0.0` release.
+    Support will be removed in the :ref:`roadmap-release-3.0.0` release.
 
 Opera (any OS, any version)
     **Community support only.** We do not receive enough traffic with this
@@ -62,11 +62,20 @@ The theme officially supports the following dependencies in your Sphinx project:
     * - Dependency
       - Versions
     * - Python
-      - 2.7 or 3.6 or greater
+      - 3.6 or greater
     * - Sphinx
-      - 1.7 up to at least 4.1
+      - 5 or greater
     * - docutils
-      - Up to 0.17
+      - >= 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
 
 .. versionadded:: 1.0
     Sphinx 4.0 support added
@@ -143,15 +152,14 @@ like Sphinx 1.8, HTML4, or required support for IE11.
 2.0.0
 ~~~~~
 
-:Planned release date: 2022 Q1
+:Planned release date: 2023 Q3
 
-This release will mark the beginning of a new round of feature development, as
+This release will drop support for old Python and Sphinx versions.
-well as a number of backward incompatible changes and deprecations.
 
-Of note, the following backwards incompatible changes are planned for this
+Note the following backwards incompatible changes are planned for this
 release:
 
-Sphinx 1.x, Sphinx 2.x, and Docutils 0.16 will not be tested
+Python < 3.6, Sphinx < 5 and Docutils < 0.14 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.
 
@@ -160,7 +168,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<=2.0.0`` until you can.
+    your dependency to ``sphinx_rtd_theme<=3`` 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
@@ -171,10 +179,31 @@ HTML4 support will be removed
 3.0.0
 ~~~~~
 
-This release is not yet planned, however there are plans to potentially replace
+:Planned release date: 2024 Q1
-Wyrm with Bootstrap in a release after 2.0.
+
+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.
 
 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.

setup.cfg

@@ -19,7 +19,7 @@ project_urls =
 	Homepage = https://sphinx-rtd-theme.readthedocs.io/
 	Source Code = https://github.com/readthedocs/sphinx_rtd_theme
 	Issue Tracker = https://github.com/readthedocs/sphinx_rtd_theme/issues
-classifiers = 
+classifiers =
 	Framework :: Sphinx
 	Framework :: Sphinx :: Theme
 	Development Status :: 5 - Production/Stable
@@ -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,9 +43,9 @@ classifiers =
 include_package_data = True
 zip_safe = False
 packages = sphinx_rtd_theme
-python_requires = >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*
+python_requires = >=3.6
 install_requires = 
-	sphinx >=1.6,<8
+	sphinx >=5,<8
 	docutils <0.19
 	sphinxcontrib-jquery >=4,<5
 tests_require = 

sphinx_rtd_theme/__init__.py

@@ -40,15 +40,11 @@ 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.warning("Python 2 is deprecated with sphinx_rtd_theme, update to Python 3")
+        logger.error("Python 2 is not supported with sphinx_rtd_theme, update to Python 3.")
-    app.require_sphinx('1.6')
+
-    if sphinx_version <= (2, 0, 0):
+    app.require_sphinx('5.0')
-        logger.warning("Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater")
+    if app.config.html4_writer:
-        if not app.config.html_experimental_html5_writer:
+        logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")
-            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.
@@ -66,18 +62,14 @@ 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__)))
 
-    if sphinx_version >= (1, 8, 0):
+    # Add Sphinx message catalog for newer versions of Sphinx
-        # 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
-        # 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')
-        rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
+    app.add_message_catalog('sphinx', rtd_locale_path)
-        app.add_message_catalog('sphinx', rtd_locale_path)
+    app.connect('config-inited', config_initiated)
-        app.connect('config-inited', config_initiated)
 
     # sphinx emits the permalink icon for headers, so choose one more in keeping with our theme
-    if sphinx_version >= (3, 5, 0):
+    app.config.html_permalinks_icon = "\uf0c1"
-        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)

tox.ini

@@ -1,14 +1,10 @@
 [tox]
 envlist =
-    # Python 2.7 support was removed in Sphinx 2
+    py{36,37,38,39,310}-sphinx{50,51,52,53}{-qa}
-    py{27}-sphinx{17,18}{-html4,-html5,}{-qa,}
+    py{38,39,310}-sphinx{60,61,62,70,71}{-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,}
+    py{39,310}-sphinx{72,latest,dev}{-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,70,71,latest}{html5}{-qa,}
+    py{311}-sphinx{53,60,61,62,70,71,72,latest,dev}{-qa}
 
 [testenv]
 setenv =
@@ -17,44 +13,18 @@ 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
-    # All these Sphinx versions actually break since docutils 0.18, so we need to add this upper bound
+    sphinx72: Sphinx>=7.2,<7.3
-    # 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
-    sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
+    dev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
 commands =
     pytest {posargs} tests/
-    !html4: sphinx-build -b html -Dhtml4_writer=0 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html
+    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