Prepare for 3.0 release (#1576)

* Tests: `sphinxdev` tox environment installs Sphinx from `master`

It seems we had a bug in the name and it wasn't installing Sphinx from `master`.
I expect this test to fail now because we pin `Sphinx<8`, but that's fine for now.

* Prepare for 3.0 release

- Drop Python <3.8
- Drop docutils <=0.18
- Add support for docutils 0.21
- Add support for Python 3.12

This follows the plan we wrote in
https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#roadmap-release-3-0-0

The main idea here is to move forward with newer versions and drop support for
old stuffs so we reduce the maintanence burden.

* Update CircleCI matrix

* More fixes to CircleCI

* Run test over Sphinx 8.0

* Update contributing guide

* Remove deprecated `readthedocs-sphinx-ext`

* Remove old Sphinx versions

* Uninstall our extension

* Show a warning if `extra_css_files` is in the `html_context`

See https://github.com/readthedocs/sphinx_rtd_theme/pull/450

* Update development page

* Add deprecate warning for `analytics_` theme options

* Update docs

* Remove unused dependency

Closes #1533

* Remove environment variables from our docs

This was already added in a more generic way to the theme itself.

* Require Sphinx >=6.0

* Deprecation warning about `get_html_theme_path`

See https://github.com/readthedocs/sphinx_rtd_theme/pull/1479#issuecomment-2296317034

.circleci/config.yml

@@ -44,54 +44,51 @@ jobs:
       - image: 'cimg/python:3.9-node'
     steps:
       - run-build: {}
-  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: "60,61,62,70,71"
   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: "60,61,62,70,71,72,73,74"
   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: "60,61,62,70,71,72,73,74,80,latest,dev"
   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: "72,73,74,80,latest,dev"
+
+  py312:
+    docker:
+      - image: 'cimg/python:3.12'
+    steps:
+      - run-tox:
+          version: py312
+          sphinx-version: "72,73,74,80,latest,dev"
 
 workflows:
   version: 2
   tests:
     jobs:
       - build
+      - py312:
+          requires:
+            - build
       - py311:
           requires:
             - build
@@ -104,9 +101,3 @@ workflows:
       - py38:
           requires:
             - build
-      - py37:
-          requires:
-            - build
-      - py36:
-          requires:
-            - build

docs/conf.py

@@ -68,10 +68,6 @@ if not 'READTHEDOCS' in os.environ:
         range(1, 100)
     ))
 
-if 'READTHEDOCS' in os.environ:
-    html_context['READTHEDOCS'] = True
-    html_context['READTHEDOCS_PROJECT'] = os.environ.get("READTHEDOCS_PROJECT")
-
 html_logo = "demo/static/logo-wordmark-light.svg"
 html_show_sourcelink = True
 html_favicon = "demo/static/favicon.ico"

docs/configuring.rst

@@ -102,7 +102,11 @@ Miscellaneous options
 
     :type: string
 
+    .. deprecated:: 3.0.0
+       The ``analytics_id`` option is deprecated, use the sphinxcontrib-googleanalytics_ extension instead.
+
     .. _gtag.js: https://developers.google.com/gtagjs
+    .. _sphinxcontrib-googleanalytics: https://pypi.org/project/sphinxcontrib-googleanalytics/
 
 .. confval:: analytics_anonymize_ip
 
@@ -111,6 +115,9 @@ Miscellaneous options
    :type: boolean
    :default: ``False``
 
+   .. deprecated:: 3.0.0
+       The ``analytics_anonymize_ip`` option is deprecated, use the sphinxcontrib-googleanalytics_ extension instead.
+
 .. confval:: canonical_url
 
     This will specify a `canonical URL`_ meta link element to tell search

docs/contributing.rst

@@ -108,13 +108,13 @@ The following cases need to be tested with changes to CSS or JavaScript:
   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``
+  We currently support Sphinx ``>=6.0``
 
 It's easiest to test combinations of dependency versions using ``tox``:
 
 .. code:: console
 
-    % tox -e py310-sphinx62
+    % tox -e py312-sphinx74
 
 If the tests and build are successful, you can view the built documentation at
 the directory noted by Sphinx:
@@ -123,9 +123,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/py312-sphinx74/tmp/html.
     ___________________________ summary ___________________________
-      py310-sphinx62: commands succeeded
+      py312-sphinx74: commands succeeded
       congratulations :)
 
 You can then open up this path with a series of browsers to test.
@@ -135,12 +135,12 @@ multiple ``tox`` environments, and open both up for comparison:
 
 .. code:: console
 
-    % tox -e py310-sphinx62
+    % tox -e py312-sphinx62
     ...
-    % tox -e py310-sphinx53
+    % tox -e py312-sphinx74
     ...
-    % firefox .tox/py310-sphinx62/tmp/html/index.html
+    % firefox .tox/py312-sphinx62/tmp/html/index.html
-    % firefox .tox/py310-sphinx53/tmp/html/index.html
+    % firefox .tox/py312-sphinx74/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
@@ -167,11 +167,11 @@ Currently, the most important environments to QA are:
    the cases above, we'll be here all day. Python 3, and latest
    minor of each major Sphinx release should give us enough work.
 
-* ``py310-sphinx53``
+* ``py312-sphinx62``
-* ``py310-sphinx62``
+* ``py312-sphinx74``
-* ``py310-sphinx72``
+* ``py312-sphinx80``
-* ``py310-sphinxlatest``
+* ``py312-sphinxlatest``
-* ``py310-sphinxdev``
+* ``py312-sphinxdev``
 
 Translations
 ============

docs/development.rst

@@ -36,13 +36,8 @@ combinations.
 
 Unsupported browser/operating system combinations include:
 
-Internet Explorer (any OS, versions <=10)
+Internet Explorer (any OS, any version)
-    **Unsupported.** IE11 is the last partially supported version. We do no
+    Support was removed in the :ref:`roadmap-release-3.0.0` release.
-    testing on prior versions.
-
-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.
 
 Opera (any OS, any version)
     **Community support only.** We do not receive enough traffic with this
@@ -62,11 +57,14 @@ The theme officially supports the following dependencies in your Sphinx project:
     * - Dependency
       - Versions
     * - Python
-      - 3.6 or greater
+      - 3.8 or greater
     * - Sphinx
-      - 5 or greater
+      - 6 or greater
     * - docutils
-      - >= 0.14, < 0.19
+      - > 0.18, < 0.22
+
+.. deprecated:: 3.0
+    Sphinx < 6 support removed
 
 .. deprecated:: 2.0
     Sphinx < 5 support removed
@@ -179,10 +177,10 @@ HTML4 support will be removed
 3.0.0
 ~~~~~
 
-:Planned release date: 2024 Q1
+:Planned release date: 2024 Q3
 
-This release is not yet fully planned.
+This release will drop support for old Python and Sphinx versions,
-However, we already know that we will be dropping support for older version of different dependencies and browsers.
+and will add support for new ones.
 
 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,

setup.cfg

@@ -29,12 +29,11 @@ classifiers =
 	Intended Audience :: Developers
 	Programming Language :: Python :: 3
 	Programming Language :: Python :: 3 :: Only
-	Programming Language :: Python :: 3.6
-	Programming Language :: Python :: 3.7
 	Programming Language :: Python :: 3.8
 	Programming Language :: Python :: 3.9
 	Programming Language :: Python :: 3.10
 	Programming Language :: Python :: 3.11
+	Programming Language :: Python :: 3.12
 	Operating System :: OS Independent
 	Topic :: Documentation
 	Topic :: Software Development :: Documentation
@@ -43,10 +42,10 @@ classifiers =
 include_package_data = True
 zip_safe = False
 packages = sphinx_rtd_theme
-python_requires = >=3.6
+python_requires = >=3.8
 install_requires = 
-	sphinx >=5,<8
+	sphinx >=6,<9
-	docutils <0.21
+	docutils >0.18,<0.22
 	sphinxcontrib-jquery >=4,<5
 tests_require = 
 	pytest
@@ -54,7 +53,6 @@ tests_require =
 [options.extras_require]
 dev = 
 	transifex-client
-	sphinxcontrib-httpdomain
 	bump2version
 	wheel
 	twine

sphinx_rtd_theme/__init__.py

@@ -21,6 +21,10 @@ logger = getLogger(__name__)
 
 def get_html_theme_path():
     """Return list of HTML theme paths."""
+    logger.warning(
+        _('Calling get_html_theme_path is deprecated. If you are calling it to define html_theme_path, you are safe to remove that code.')
+    )
+
     cur_dir = path.abspath(path.dirname(path.dirname(__file__)))
     return cur_dir
 
@@ -32,6 +36,21 @@ def config_initiated(app, config):
             _('The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead.')
         )
 
+    if theme_options.get("analytics_id"):
+        logger.warning(
+            _('The analytics_id option is deprecated, use the sphinxcontrib-googleanalytics extension instead.')
+        )
+
+    if theme_options.get("analytics_anonymize_ip"):
+        logger.warning(
+            _('The analytics_anonymize_ip option is deprecated, use the sphinxcontrib-googleanalytics extension instead.')
+        )
+
+    if "extra_css_files" in config.html_context:
+        logger.warning(
+            _('The extra_css_file option is deprecated, use the html_css_files option from Sphinx instead.')
+        )
+
 
 def extend_html_context(app, pagename, templatename, context, doctree):
      # Add ``sphinx_version_info`` tuple for use in Jinja templates
@@ -52,7 +71,7 @@ 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')
+    app.require_sphinx('6.0')
     if app.config.html4_writer:
         logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")
 

tests/util.py

@@ -34,7 +34,6 @@ def build(root, builder='html', **kwargs):
     confoverrides['html_theme'] = 'sphinx_rtd_theme'
     extensions = confoverrides.get('extensions', [])
     extensions.append('sphinx_rtd_theme')
-    extensions.append('readthedocs_ext.readthedocs')
     confoverrides['extensions'] = extensions
     kwargs['confoverrides'] = confoverrides
 
@@ -55,7 +54,6 @@ def build(root, builder='html', **kwargs):
 
 
 def build_all(root, **kwargs):
-    for builder in ['html', 'singlehtml', 'readthedocs', 'readthedocsdirhtml',
+    for builder in ['html', 'singlehtml']:
-                    'readthedocssinglehtml', 'readthedocssinglehtmllocalmedia']:
         with build(root, builder, **kwargs) as ret:
             yield ret

tox.ini

@@ -1,28 +1,22 @@
 [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}
+    py{39,310,311,312}-sphinx{72,73,74,80}{-qa}
-    # Python 3.11 working from Sphinx 5.3 and up
+    py{310,311,312}-sphinx{latest,dev}{-qa}
-    py{311}-sphinx{53,60,61,62,70,71,72,latest,dev}{-qa}
 
 [testenv]
 setenv =
     LANG=C
 deps =
     .
-    readthedocs-sphinx-ext
     pytest
-    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
+    sphinx80: Sphinx>=8.0,<8.1
     sphinxlatest: Sphinx
     sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
 allowlist_externals =