3.1.0rc2 with support for docutils 0.22 (#1674)

* Add support for docutils 0.22

No errors when building the docs or visual differences.

Related #1665

* Update docs

.circleci/config.yml

@@ -44,54 +44,62 @@ 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"
   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,81,82,90,latest"
+
+  py312:
+    docker:
+      - image: 'cimg/python:3.12'
+    steps:
+      - run-tox:
+          version: py312
+          sphinx-version: "72,73,74,80,81,82,90,latest,dev"
+
+  py313:
+    docker:
+      - image: 'cimg/python:3.13'
+    steps:
+      - run-tox:
+          version: py313
+          sphinx-version: "72,73,74,80,81,82,90,latest,dev"
 
 workflows:
   version: 2
   tests:
     jobs:
       - build
+      - py313:
+          requires:
+            - build
+      - py312:
+          requires:
+            - build
       - py311:
           requires:
             - build
@@ -104,9 +112,3 @@ workflows:
       - py38:
           requires:
             - build
-      - py37:
-          requires:
-            - build
-      - py36:
-          requires:
-            - build

.github/CODE_OF_CONDUCT.md

@@ -2,4 +2,4 @@
 
 A copy of our code of conduct can be found on Read the Docs as seen below.
 
-http://docs.readthedocs.io/en/latest/code-of-conduct.html
+https://docs.readthedocs.com/dev/stable/code-of-conduct.html

.gitignore

@@ -23,8 +23,6 @@ sphinx_rtd_theme/static/fonts/RobotoSlab/
 .node-version
 .tool-versions
 .nvmrc
-sphinx_rtd_theme/static/js/html5shiv.min.js
-sphinx_rtd_theme/static/js/html5shiv-printshiv.min.js
 .direnv/
 .envrc
 # Used for dockerized builds

.readthedocs.yml

@@ -1,9 +1,9 @@
 version: 2
 
 build:
-  os: "ubuntu-22.04"
+  os: "ubuntu-24.04"
   tools:
-    python: "3.10"
+    python: "3.12"
 
 python:
   install:

Dockerfile

@@ -1,4 +1,4 @@
-# This implicitely includes Python 3.10
+# This implicitly includes Python 3.10
 FROM node:14-alpine
 
 # Do not use --update since that will also fetch the

MANIFEST.in

@@ -7,6 +7,7 @@ recursive-include sphinx_rtd_theme *.css
 recursive-include sphinx_rtd_theme *.eot
 recursive-include sphinx_rtd_theme *.html
 recursive-include sphinx_rtd_theme *.js
+recursive-include sphinx_rtd_theme *.js_t
 recursive-include sphinx_rtd_theme *.svg
 recursive-include sphinx_rtd_theme *.ttf
 recursive-include sphinx_rtd_theme *.woff

docs/_static/addons.mocked.json

@@ -0,0 +1,369 @@
+{
+    "addons": {
+        "analytics": {
+            "code": null,
+            "enabled": true
+        },
+        "ethicalads": {
+            "ad_free": false,
+            "campaign_types": [
+                "community",
+                "house",
+                "paid"
+            ],
+            "enabled": true,
+            "keywords": [
+                "only words"
+            ],
+            "publisher": "readthedocs"
+        },
+        "external_version_warning": {
+            "enabled": true
+        },
+        "flyout": {
+            "enabled": true
+        },
+        "hotkeys": {
+            "doc_diff": {
+                "enabled": true,
+                "trigger": "KeyD"
+            },
+            "enabled": true,
+            "search": {
+                "enabled": true,
+                "trigger": "Slash"
+            }
+        },
+        "non_latest_version_warning": {
+            "enabled": true
+        },
+        "search": {
+            "default_filter": "project:sphinx-rtd-theme/stable",
+            "enabled": true,
+            "filters": [
+                [
+                    "Include subprojects",
+                    "subprojects:sphinx-rtd-theme/stable"
+                ]
+            ]
+        }
+    },
+    "api_version": "1",
+    "builds": {
+        "current": {
+            "commit": "7c9b1b5d391f6d7fae72274393eb25d1df96e546",
+            "created": "2023-11-28T04:14:06.510677Z",
+            "duration": 42,
+            "error": "",
+            "finished": "2023-11-28T04:14:48.510Z",
+            "id": 22677856,
+            "project": "sphinx-rtd-theme",
+            "state": {
+                "code": "finished",
+                "name": "Finished"
+            },
+            "success": true,
+            "urls": {
+                "build": "https://readthedocs.org/projects/sphinx-rtd-theme/builds/22677856/",
+                "project": "https://readthedocs.org/projects/sphinx-rtd-theme/",
+                "version": "https://readthedocs.org/projects/sphinx-rtd-theme/version/stable/edit/"
+            },
+            "version": "stable"
+        }
+    },
+    "domains": {
+        "dashboard": "readthedocs.org"
+    },
+    "projects": {
+        "current": {
+            "created": "2017-12-21T04:04:42.561793Z",
+            "default_branch": "master",
+            "default_version": "stable",
+            "external_builds_privacy_level": "public",
+            "homepage": null,
+            "id": 170010,
+            "language": {
+                "code": "en",
+                "name": "English"
+            },
+            "modified": "2021-03-16T17:13:52.465051Z",
+            "name": "sphinx_rtd_theme",
+            "privacy_level": "public",
+            "programming_language": {
+                "code": "words",
+                "name": "Only Words"
+            },
+            "repository": {
+                "type": "git",
+                "url": "https://github.com/readthedocs/sphinx_rtd_theme"
+            },
+            "single_version": false,
+            "slug": "sphinx-rtd-theme",
+            "subproject_of": null,
+            "tags": [],
+            "translation_of": null,
+            "urls": {
+                "builds": "https://readthedocs.org/projects/sphinx-rtd-theme/builds/",
+                "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/stable/",
+                "downloads": "https://readthedocs.org/projects/sphinx-rtd-theme/downloads/",
+                "home": "https://readthedocs.org/projects/sphinx-rtd-theme/",
+                "versions": "https://readthedocs.org/projects/sphinx-rtd-theme/versions/"
+            },
+            "users": [
+                {
+                    "username": "eric"
+                },
+                {
+                    "username": "humitos"
+                },
+                {
+                    "username": "agj"
+                }
+            ],
+            "versioning_scheme": "multiple_versions_with_translations"
+        },
+        "translations": []
+    },
+    "readthedocs": {
+        "analytics": {
+            "code": null
+        }
+    },
+    "versions": {
+        "active": [
+            {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 6692534,
+                "identifier": "b07560bf97dad3a4266f6145bd4b662ac708ab00",
+                "privacy_level": "public",
+                "ref": null,
+                "slug": "0.5.2",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/0.5.2/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/0.5.2/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/0.5.2/"
+                },
+                "verbose_name": "0.5.2"
+            },
+            {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 7273098,
+                "identifier": "c9b1bde560d8ee31400e4e4f92f2e8d7a42265ce",
+                "privacy_level": "public",
+                "ref": null,
+                "slug": "1.0.0",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/1.0.0/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/1.0.0/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/1.0.0/"
+                },
+                "verbose_name": "1.0.0"
+            },
+            {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 10496721,
+                "identifier": "f854c890e1445b99a43ac5f10463a5df83739a2e",
+                "privacy_level": "public",
+                "ref": null,
+                "slug": "1.1.1",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/1.1.1/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/1.1.1/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/1.1.1/"
+                },
+                "verbose_name": "1.1.1"
+            },
+            {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 16340532,
+                "identifier": "9899ee4ee2f547f81e51297dc12317f018e62fdd",
+                "privacy_level": "public",
+                "ref": null,
+                "slug": "1.2.2",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/1.2.2/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/1.2.2/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/1.2.2/"
+                },
+                "verbose_name": "1.2.2"
+            },
+            {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 17681643,
+                "identifier": "15ed4de08de55f7066ff4f2ac39883a397db30d3",
+                "privacy_level": "public",
+                "ref": null,
+                "slug": "1.3.0",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/1.3.0/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/1.3.0/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/1.3.0/"
+                },
+                "verbose_name": "1.3.0"
+            },
+            {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 18862205,
+                "identifier": "7c9b1b5d391f6d7fae72274393eb25d1df96e546",
+                "privacy_level": "public",
+                "ref": null,
+                "slug": "2.0.0",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/2.0.0/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/2.0.0/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/2.0.0/"
+                },
+                "verbose_name": "2.0.0"
+            },
+            {
+                "active": true,
+                "aliases": [
+                    {
+                        "active": true,
+                        "aliases": [],
+                        "built": true,
+                        "downloads": {},
+                        "hidden": false,
+                        "id": 18862205,
+                        "identifier": "7c9b1b5d391f6d7fae72274393eb25d1df96e546",
+                        "privacy_level": "public",
+                        "ref": null,
+                        "slug": "2.0.0",
+                        "type": "tag",
+                        "urls": {
+                            "dashboard": {
+                                "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/2.0.0/edit/"
+                            },
+                            "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/2.0.0/",
+                            "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/2.0.0/"
+                        },
+                        "verbose_name": "2.0.0"
+                    }
+                ],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 3271725,
+                "identifier": "7c9b1b5d391f6d7fae72274393eb25d1df96e546",
+                "privacy_level": "public",
+                "ref": "2.0.0",
+                "slug": "stable",
+                "type": "tag",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/stable/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/stable/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/2.0.0/"
+                },
+                "verbose_name": "stable"
+            },
+            {
+                "active": true,
+                "aliases": [],
+                "built": true,
+                "downloads": {},
+                "hidden": false,
+                "id": 3271688,
+                "identifier": "master",
+                "privacy_level": "public",
+                "ref": null,
+                "slug": "latest",
+                "type": "branch",
+                "urls": {
+                    "dashboard": {
+                        "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/latest/edit/"
+                    },
+                    "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/latest/",
+                    "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/master/"
+                },
+                "verbose_name": "latest"
+            }
+        ],
+        "current": {
+            "active": true,
+            "aliases": [
+                {
+                    "active": true,
+                    "aliases": [],
+                    "built": true,
+                    "downloads": {},
+                    "hidden": false,
+                    "id": 18862205,
+                    "identifier": "7c9b1b5d391f6d7fae72274393eb25d1df96e546",
+                    "privacy_level": "public",
+                    "ref": null,
+                    "slug": "2.0.0",
+                    "type": "tag",
+                    "urls": {
+                        "dashboard": {
+                            "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/2.0.0/edit/"
+                        },
+                        "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/2.0.0/",
+                        "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/2.0.0/"
+                    },
+                    "verbose_name": "2.0.0"
+                }
+            ],
+            "built": true,
+            "downloads": {},
+            "hidden": false,
+            "id": 3271725,
+            "identifier": "7c9b1b5d391f6d7fae72274393eb25d1df96e546",
+            "privacy_level": "public",
+            "ref": "2.0.0",
+            "slug": "stable",
+            "type": "tag",
+            "urls": {
+                "dashboard": {
+                    "edit": "https://readthedocs.org/projects/sphinx-rtd-theme/version/stable/edit/"
+                },
+                "documentation": "https://sphinx-rtd-theme.readthedocs.io/en/stable/",
+                "vcs": "https://github.com/readthedocs/sphinx_rtd_theme/tree/2.0.0/"
+            },
+            "verbose_name": "stable"
+        }
+    }
+}

docs/_static/debug.js

@@ -4,4 +4,40 @@ $(function () {
   $("[data-toggle='rst-debug-badge']").on("click", function () {
     $("[data-toggle='rst-versions']").toggleClass("rst-badge");
   });
-})
+});
+
+
+const EVENT_READTHEDOCS_ADDONS_DATA_READY = "readthedocs-addons-data-ready";
+
+fetch("_static/addons.mocked.json", { method: "GET" })
+  .then((response) => {
+    if (!response.ok) {
+      throw new Error("Error downloading Read the Docs Addons mocked data");
+    }
+    return response.json();
+  })
+  .then((data) => {
+    return dispatchEvent(
+      EVENT_READTHEDOCS_ADDONS_DATA_READY,
+      new ReadTheDocsEventData(data),
+    );
+  });
+
+
+// ``ReadTheDocsEventData`` and ``dispatchEvent``
+// are borrowed and adapted from Read the Docs Addons.
+// https://github.com/readthedocs/addons
+class ReadTheDocsEventData {
+  constructor(data) {
+    this._data = data;
+  }
+
+  data() {
+    return this._data;
+  }
+}
+
+function dispatchEvent(eventName, data) {
+  const event = new CustomEvent(eventName, { detail: data });
+  document.dispatchEvent(event);
+}

docs/_templates/layout.html

@@ -1,55 +0,0 @@
-{%- extends "!layout.html" %}
-
-{#-
-
-This template exists as a way to implement a version menu without changing what
-the theme normally renders the menu on local builds and on builds on Read the
-Docs. This is for local testing purposes only.
-
-#}
-
-{%- block footer %}
-  {%- if not READTHEDOCS %}
-    <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Versions') }}">
-      <span class="rst-current-version" data-toggle="rst-current-version">
-        <span class="fa fa-book"> Read the Docs</span>
-        v: latest
-        <span class="fa fa-caret-down"></span>
-      </span>
-      <div class="rst-other-versions">
-        <dl>
-          <dt>{{ _('Versions') }}</dt>
-          {%- if test_versions %}
-            {%- for version in test_versions %}
-            <dd><a href="#">{{ version }}</a></dd>
-            {%- endfor %}
-          {%- else %}
-            <dd><a href="#">latest</a></dd>
-            <dd><a href="#">1.0</a></dd>
-            <dd><a href="#">1.1</a></dd>
-          {%- endif %}
-        </dl>
-        <dl>
-          <dt>{{ _('Downloads') }}</dt>
-          <dd><a href="#">PDF</a></dd>
-          <dd><a href="#">ePub</a></dd>
-          <dd><a href="#">HTML</a></dd>
-        </dl>
-        <dl>
-          {#- Translators: The phrase "Read the Docs" is not translated #}
-          <dt>{{ _('On Read the Docs') }}</dt>
-            <dd>
-              <a href="#">{{ _('Project Home') }}</a>
-            </dd>
-            <dd>
-              <a href="#">{{ _('Builds') }}</a>
-            </dd>
-        </dl>
-        <dl>
-          <dt>Debug</dt>
-          <dd><a href="#" data-toggle="rst-debug-badge">Swap badge position</a></dd>
-        </dl>
-      </div>
-    </div>
-  {%- endif %}
-{%- endblock %}

docs/changelog.rst

@@ -4,16 +4,136 @@ Changelog
 
 .. seealso:: :ref:`howto_upgrade`
 
-.. |theme_version| replace:: 2.0.0rc2
+.. |theme_version| replace:: 3.1.0rc1
 
-.. _release-2.0.0:
+.. _release-3.1.0rc2:
 
-2.0.0rc2
+3.1.0rc2
+========
+
+* Added support for docutils 0.22
+
+.. _release-3.1.0rc1:
+
+3.1.0rc1
+========
+
+* Added support for Sphinx 9.x
+
+.. _release-3.0.2:
+
+3.0.2
+=====
+
+* Show current translation when the flyout is attached
+* Fix JavaScript issue that didn't allow users to disable selectors
+
+.. _release-3.0.1:
+
+3.0.1
+=====
+
+* Use black color for text in selectors.
+
+.. _release-3.0.0:
+
+3.0.0
+=====
+
+Final version.
+
+.. _release-3.0.0rc4:
+
+3.0.0rc4
+========
+
+Fixes
+-----
+
+* Trigger "Read the Docs Search addon" when focusing the "Search docs" input in the navbar.
+
+.. _release-3.0.0rc3:
+
+3.0.0rc3
+========
+
+Fixes
+-----
+
+* Show hidden version in selector if it's the current active version
+
+.. _release-3.0.0rc2:
+
+3.0.0rc2
 ========
 
 Added
 -----
 
+* Render version and language selectors below the documentation's title (top left).
+  This can be controlled via the new theme options ``version_selector`` and ``language_selector``.
+
+.. _release-3.0.0rc1:
+
+3.0.0rc1
+========
+
+Added
+-----
+
+* Added support for Sphinx 8.
+* Added support for Python 3.12.
+* Added support for docutils ``>0.18, <0.22``.
+* Populate ``html_context`` with all the environment variables starting with ``READTHEDOCS_``.
+
+Deprecations
+------------
+
+* Drop support for Sphinx ``<6.0``.
+* Drop support for Python ``<3.8``.
+* ``analytics_id`` and ``analytics_anonymize_ip`` are deprecated, use sphinxcontrib-googleanalytics_ instead.
+* Drop support for all versions of Internet Explorer.
+* Raise a warning when defining ``html_theme_path``. This was an old config that's not required anymore.
+* ``extra_css_files`` is deprecated and support will be removed in a future version.
+
+.. _sphinxcontrib-googleanalytics: https://pypi.org/project/sphinxcontrib-googleanalytics/
+
+.. _release-2.1.0rc2:
+
+2.1.0rc2
+========
+
+Added
+-----
+
+* Added ``flyout_display`` option to display the flyout
+  ``attached`` (bottom of the sidebard) or ``hidden`` (default).
+
+.. _release-2.1.0rc1:
+
+2.1.0rc1
+========
+
+Added
+-----
+
+* Render the menu versions/languages selector (flyout)
+  using the new ``readthedocs-addons-data-ready`` Read the Docs Addons ``CustomEvent``.
+
+Deprecations
+------------
+
+* Remove ``html5shiv``.
+
+.. _release-2.0.0:
+
+2.0.0
+=====
+
+Added
+-----
+
+* Support for Sphinx versions ``6.x`` and ``7.x``
 * Support for docutils ``<=0.20``
 
 Deprecations

docs/conf.py

@@ -61,12 +61,7 @@ html_context = {}
 if not 'READTHEDOCS' in os.environ:
     html_static_path = ['_static/']
     html_js_files = ['debug.js']
-
-    # Add fake versions for local QA of the menu
-    html_context['test_versions'] = list(map(
-        lambda x: str(x / 10),
-        range(1, 100)
-    ))
+    html_context["DEBUG"] = True
 
 html_logo = "demo/static/logo-wordmark-light.svg"
 html_show_sourcelink = True

docs/configuring.rst

@@ -16,11 +16,13 @@ For example:
         'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
         'analytics_anonymize_ip': False,
         'logo_only': False,
-        'display_version': True,
         'prev_next_buttons_location': 'bottom',
         'style_external_links': False,
         'vcs_pageview_mode': '',
         'style_nav_header_background': 'white',
+        'flyout_display': 'hidden',
+        'version_selector': True,
+        'language_selector': True,
         # Toc options
         'collapse_navigation': True,
         'sticky_navigation': True,
@@ -101,7 +103,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
 
@@ -110,6 +116,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
@@ -131,7 +140,11 @@ Miscellaneous options
     If ``True``, the version number is shown at the top of the sidebar.
 
     :type: boolean
-    :default: ``True``
+    :default: ``False``
+
+    .. deprecated:: 3.0.0
+
+       Removed in favor of ``version_selector`` and ``language_selector``.
 
 .. confval:: logo_only
 
@@ -174,6 +187,36 @@ Miscellaneous options
     :type: string
     :default: ``#2980B9``
 
+.. confval:: flyout_display
+
+    Specify how to display the flyout (language and version selector).
+    This can be either ``attached`` or ``hidden``.
+    ``attached`` means that it will show the flyout in the bottom of the sidebar.
+    You will need to disable the default `Read the Docs flyout <https://docs.readthedocs.io/en/stable/flyout-menu.html>`_ in order to not have 2 flyouts showing.
+
+    :type: str
+    :default: ``hidden``
+
+.. confval:: version_selector
+
+    Display a version selector below the title.
+    This feature makes usage of `Read the Docs Addons <https://docs.readthedocs.io/page/addons.html>`_ for this,
+    so it's required the documentation to be hosted on Read the Docs.
+    It only appears when there are more than 1 active version.
+
+    :type: boolean
+    :default: ``True``
+
+.. confval:: language_selector
+
+    Display a language selector below the title.
+    This feature makes usage of `Read the Docs Addons <https://docs.readthedocs.io/page/addons.html>`_ for this,
+    so it's required the documentation to be served on Read the Docs.
+    It only appears when there is more than 1 active language.
+
+    :type: boolean
+    :default: ``True``
+
 
 File-wide metadata
 ==================

docs/contributing.rst

@@ -86,7 +86,7 @@ Use the following steps:
 
     # Runs the development webserver
     $ docker-compose run sphinx_rtd_theme dev
-    
+
     # If you want to copy stuff out of the Docker environment, run this make
     # target or read the actual Makefile to see what is going on.
     # We suggest running this command every time that you want to quickly build
@@ -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/py310-sphinx53/tmp/html/index.html
+    % firefox .tox/py312-sphinx62/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``
-* ``py310-sphinx62``
-* ``py310-sphinx72``
-* ``py310-sphinxlatest``
-* ``py310-sphinxdev``
+* ``py312-sphinx62``
+* ``py312-sphinx74``
+* ``py312-sphinx80``
+* ``py312-sphinxlatest``
+* ``py312-sphinxdev``
 
 Translations
 ============
@@ -227,6 +227,7 @@ Releasing the theme
 
 To release a new version of the theme, core team will take the following steps:
 
+#. Install the required depedencies with ``pip install '.[dev]'``.
 #. Bump the version by running ``bump2version [major|minor|patch|dev]``.
    This will automatically increase the correct part(s) of the version number,
    you do not need to specify the exact version number.
@@ -247,7 +248,7 @@ To release a new version of the theme, core team will take the following steps:
 #. Commit these changes to a pull request.
 #. Merge the pull request after review.
 #. Check out ``master`` branch locally for tagging. **Remember to pull from remote**.
-#. Tag the release in git: ``git tag -s $NEW_VERSION``.
+#. Tag the release in git: ``git tag $NEW_VERSION``.
 #. Push the tag to GitHub: ``git push --tags origin``.
 #. Upload the package to PyPI:
 

docs/development.rst

@@ -36,13 +36,8 @@ combinations.
 
 Unsupported browser/operating system combinations include:
 
-Internet Explorer (any OS, versions <=10)
-    **Unsupported.** IE11 is the last partially supported version. We do no
-    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.
+Internet Explorer (any OS, any version)
+    Support was 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.23
+
+.. 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.
-However, we already know that we will be dropping support for older version of different dependencies and browsers.
+This release will drop support for old Python and Sphinx versions,
+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,

docs/installing.rst

@@ -31,15 +31,13 @@ In your Sphinx project's ``conf.py`` file, add ``sphinx_rtd_theme`` to the list
 
 .. note::
 
-   Adding this theme as an extension is what enables localization of theme
-   strings in your translated output. If these strings are not translated in
-   your output, either we lack the localized strings for your locale, or you
-   are using an old version of the theme.
+   Adding this theme as an extension activates the ``sphinxcontrib-jquery`` extension,
+   which is required for search, smooth scrolling, and the flyout menu.
+   If any of these features don't work, make sure you have the theme declared in your ``extensions``.
 
-   ..
-      comment about this note: it's possibly not necessary to add the theme as an extension.
-      Rather, this is an issue caused by setting html_theme_path.
-      See: https://github.com/readthedocs/readthedocs.org/pull/9654
+   .. More context for this note:
+        * https://github.com/readthedocs/sphinx_rtd_theme/issues/1434#issuecomment-2288359582
+        * https://github.com/readthedocs/sphinx_rtd_theme/issues/1222#issuecomment-2296703160
 
 
 .. _howto_upgrade:

docs/requirements.txt

@@ -1 +1 @@
-sphinx>=7.1,<7.2
+sphinx~=9.0

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx_rtd_theme",
-  "version": "2.0.0rc2",
+  "version": "3.1.0rc2",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {
@@ -637,6 +637,16 @@
       "dev": true,
       "optional": true
     },
+    "bindings": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz",
+      "integrity": "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==",
+      "dev": true,
+      "optional": true,
+      "requires": {
+        "file-uri-to-path": "1.0.0"
+      }
+    },
     "block-stream": {
       "version": "0.0.9",
       "resolved": "https://registry.npmjs.org/block-stream/-/block-stream-0.0.9.tgz",
@@ -1472,26 +1482,6 @@
       "integrity": "sha512-XgZ0pFcakEUlbwQEVNg3+QAis1FyTL3Qel9FYy8pSkQqoG3PNoT0bOCQtOXcOkur21r2Eq2kI+IE+gsmAEVlYw==",
       "dev": true
     },
-    "copy-webpack-plugin": {
-      "version": "5.1.2",
-      "resolved": "https://registry.npmjs.org/copy-webpack-plugin/-/copy-webpack-plugin-5.1.2.tgz",
-      "integrity": "sha512-Uh7crJAco3AjBvgAy9Z75CjK8IG+gxaErro71THQ+vv/bl4HaQcpkexAY8KVW/T6D2W2IRr+couF/knIRkZMIQ==",
-      "dev": true,
-      "requires": {
-        "cacache": "^12.0.3",
-        "find-cache-dir": "^2.1.0",
-        "glob-parent": "^3.1.0",
-        "globby": "^7.1.1",
-        "is-glob": "^4.0.1",
-        "loader-utils": "^1.2.3",
-        "minimatch": "^3.0.4",
-        "normalize-path": "^3.0.0",
-        "p-limit": "^2.2.1",
-        "schema-utils": "^1.0.0",
-        "serialize-javascript": "^4.0.0",
-        "webpack-log": "^2.0.0"
-      }
-    },
     "core-util-is": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
@@ -2045,32 +2035,6 @@
         }
       }
     },
-    "dir-glob": {
-      "version": "2.2.2",
-      "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-2.2.2.tgz",
-      "integrity": "sha512-f9LBi5QWzIW3I6e//uxZoLBlUt9kcp66qo0sSCxL6YZKc75R1c4MFCoe/LaZiBGmgujvQdxc5Bn3QhfyvK5Hsw==",
-      "dev": true,
-      "requires": {
-        "path-type": "^3.0.0"
-      },
-      "dependencies": {
-        "path-type": {
-          "version": "3.0.0",
-          "resolved": "https://registry.npmjs.org/path-type/-/path-type-3.0.0.tgz",
-          "integrity": "sha512-T2ZUsdZFHgA3u4e5PfPbjd7HDDpxPnQb5jN0SrDsjNSuVXHJqtwTnWqG0B1jZrgmJ/7lj1EmVIByWt1gxGkWvg==",
-          "dev": true,
-          "requires": {
-            "pify": "^3.0.0"
-          }
-        },
-        "pify": {
-          "version": "3.0.0",
-          "resolved": "https://registry.npmjs.org/pify/-/pify-3.0.0.tgz",
-          "integrity": "sha512-C3FsVNH1udSEX48gGX1xfvwTWfsYWj5U+8/uK15BGzIGrKoUpghX8hWZwa/OFnakBiiVNmBvemTJR5mcy7iPcg==",
-          "dev": true
-        }
-      }
-    },
     "dns-equal": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/dns-equal/-/dns-equal-1.0.0.tgz",
@@ -2708,6 +2672,13 @@
         "schema-utils": "^1.0.0"
       }
     },
+    "file-uri-to-path": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz",
+      "integrity": "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==",
+      "dev": true,
+      "optional": true
+    },
     "fill-range": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-4.0.0.tgz",
@@ -3098,28 +3069,6 @@
         "define-properties": "^1.1.3"
       }
     },
-    "globby": {
-      "version": "7.1.1",
-      "resolved": "https://registry.npmjs.org/globby/-/globby-7.1.1.tgz",
-      "integrity": "sha512-yANWAN2DUcBtuus5Cpd+SKROzXHs2iVXFZt/Ykrfz6SAXqacLX25NZpltE+39ceMexYF4TtEadjuSTw8+3wX4g==",
-      "dev": true,
-      "requires": {
-        "array-union": "^1.0.1",
-        "dir-glob": "^2.0.0",
-        "glob": "^7.1.2",
-        "ignore": "^3.3.5",
-        "pify": "^3.0.0",
-        "slash": "^1.0.0"
-      },
-      "dependencies": {
-        "pify": {
-          "version": "3.0.0",
-          "resolved": "https://registry.npmjs.org/pify/-/pify-3.0.0.tgz",
-          "integrity": "sha512-C3FsVNH1udSEX48gGX1xfvwTWfsYWj5U+8/uK15BGzIGrKoUpghX8hWZwa/OFnakBiiVNmBvemTJR5mcy7iPcg==",
-          "dev": true
-        }
-      }
-    },
     "globule": {
       "version": "1.3.4",
       "resolved": "https://registry.npmjs.org/globule/-/globule-1.3.4.tgz",
@@ -3384,12 +3333,6 @@
       "integrity": "sha512-8nxjcBcd8wovbeKx7h3wTji4e6+rhaVuPNpMqwWgnHh+N9ToqsCs6XztWRBPQ+UtzsoMAdKZtUENoVzU/EMtZA==",
       "dev": true
     },
-    "html5shiv": {
-      "version": "3.7.3",
-      "resolved": "https://registry.npmjs.org/html5shiv/-/html5shiv-3.7.3.tgz",
-      "integrity": "sha512-SZwGvLGNtgp8GbgFX7oXEp8OR1aBt5LliX6dG0kdD1kl3KhMonN0QcSa/A3TsTgFewaGCbIryQunjayWDXzxmw==",
-      "dev": true
-    },
     "http-deceiver": {
       "version": "1.2.7",
       "resolved": "https://registry.npmjs.org/http-deceiver/-/http-deceiver-1.2.7.tgz",
@@ -3485,12 +3428,6 @@
       "integrity": "sha512-DUNFN5j7Tln0D+TxzloUjKB+CtVu6myn0JEFak6dG18mNt9YkQ6lzGCdafwofISZ1lLF3xRHJ98VKy9ynkcFaA==",
       "dev": true
     },
-    "ignore": {
-      "version": "3.3.10",
-      "resolved": "https://registry.npmjs.org/ignore/-/ignore-3.3.10.tgz",
-      "integrity": "sha512-Pgs951kaMm5GXP7MOvxERINe3gsaVjUWFm+UZPSq9xYriQAksyhg0csnS0KXSNRD5NmNdapXEpjxG49+AKh/ug==",
-      "dev": true
-    },
     "import-fresh": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-2.0.0.tgz",
@@ -6557,12 +6494,6 @@
         }
       }
     },
-    "slash": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/slash/-/slash-1.0.0.tgz",
-      "integrity": "sha512-3TYDR7xWt4dIqV2JauJr+EJeW356RXijHeUlO+8djJ+uBXPn8/2dpzBc8yQhh583sVvc9CvFAeQVgijsH+PNNg==",
-      "dev": true
-    },
     "snapdragon": {
       "version": "0.8.2",
       "resolved": "https://registry.npmjs.org/snapdragon/-/snapdragon-0.8.2.tgz",
@@ -7780,6 +7711,7 @@
           "dev": true,
           "optional": true,
           "requires": {
+            "bindings": "^1.5.0",
             "nan": "^2.12.1"
           }
         },
@@ -8046,6 +7978,7 @@
           "dev": true,
           "optional": true,
           "requires": {
+            "bindings": "^1.5.0",
             "nan": "^2.12.1"
           }
         },

package.json

@@ -1,7 +1,7 @@
 {
   "name": "sphinx_rtd_theme",
   "main": "js/theme.js",
-  "version": "2.0.0rc2",
+  "version": "3.1.0rc2",
   "scripts": {
     "dev": "webpack-dev-server --open --config webpack.dev.js",
     "build": "webpack --config webpack.prod.js",
@@ -17,15 +17,12 @@
     "url": "https://github.com/readthedocs/sphinx_rtd_theme/issues"
   },
   "homepage": "https://github.com/readthedocs/sphinx_rtd_theme",
-  "dependencies": {},
   "devDependencies": {
     "bourbon": "~4.3",
     "bourbon-neat": "~1.9",
-    "copy-webpack-plugin": "^5.1.2",
     "css-loader": "^3.6.0",
     "file-loader": "^3.0.1",
     "font-awesome": "^4.7.0",
-    "html5shiv": "^3.7.3",
     "imports-loader": "^0.8.0",
     "jquery": "^3.6.0",
     "lato-font": "^3.0.0",

pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+filterwarnings =
+    # Ignore external dependencies warning deprecations
+    # Sphinx
+    # ignore::sphinx.deprecation.RemovedInSphinx90Warning

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.0.0rc2
+current_version = 3.1.0rc2
 commit = false
 tag = false
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)((?P<release>[a-z]+)(?P<dev>\d+))?
@@ -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
-	docutils <0.21
+	sphinx >=6,<10
+	docutils >0.18,<0.23
 	sphinxcontrib-jquery >=4,<5
 tests_require = 
 	pytest
@@ -54,9 +53,9 @@ tests_require =
 [options.extras_require]
 dev = 
 	transifex-client
-	sphinxcontrib-httpdomain
 	bump2version
 	wheel
+	twine
 
 [options.entry_points]
 sphinx.html_themes = 

setup.py

@@ -86,7 +86,7 @@ class TransifexCommand(distutils.cmd.Command):
 
 
 setup(
-    version='2.0.0rc2',
+    version='3.1.0rc2',
     cmdclass={
         'update_translations': UpdateTranslationsCommand,
         'transifex': TransifexCommand,

sphinx_rtd_theme/__init__.py

@@ -4,6 +4,7 @@ Sphinx Read the Docs theme.
 From https://github.com/ryan-roemer/sphinx-bootstrap-theme.
 """
 
+import os
 from os import path
 from sys import version_info as python_version
 
@@ -12,7 +13,7 @@ from sphinx.locale import _
 from sphinx.util.logging import getLogger
 
 
-__version__ = '2.0.0rc2'
+__version__ = '3.1.0rc2'
 __version_full__ = __version__
 
 logger = getLogger(__name__)
@@ -20,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
 
@@ -31,18 +36,42 @@ 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
      context['sphinx_version_info'] = sphinx_version
 
+     # Inject all the Read the Docs environment variables in the context:
+     # https://docs.readthedocs.io/en/stable/reference/environment-variables.html
+     context['READTHEDOCS'] = os.environ.get("READTHEDOCS", False) == "True"
+     if context['READTHEDOCS']:
+         for key, value in os.environ.items():
+             if key.startswith("READTHEDOCS_"):
+                 context[key] = value
+
+
 
 # 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')
+    app.require_sphinx('6.0')
     if app.config.html4_writer:
         logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")
 

sphinx_rtd_theme/layout.html

@@ -7,16 +7,18 @@
   {%- set titlesuffix = "" %}
 {%- endif %}
 {%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %}
-{%- set sphinx_writer = 'writer-html5' if html5_doctype else 'writer-html4' -%}
 
 {# Build sphinx_version_info tuple from sphinx_version string in pure Jinja #}
 {%- set (_ver_major, _ver_minor) = (sphinx_version.split('.') | list)[:2] | map('int') -%}
 {%- 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="writer-html5" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
 <head>
   <meta charset="utf-8" />
+  {%- if READTHEDOCS and not embedded %}
+  <meta name="readthedocs-addons-api-version" content="1">
+  {%- endif %}
   {{- metatags }}
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   {%- block htmltitle %}
@@ -24,25 +26,27 @@
   {%- endblock -%}
 
   {#- CSS #}
-  {%- if sphinx_version_info < (4, 0) -%}
-    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
-    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
-  {%- endif %}
-  {%- for css in css_files %}
-    {{ css_tag(css) }}
+  {%- for css_file in css_files %}
+    {%- if css_file|attr("filename") %}
+      {{ css_tag(css_file) }}
+    {%- else %}
+      <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
+    {%- endif %}
   {%- endfor %}
 
-  {%- for cssfile in extra_css_files %}
-    {{ css_tag(cssfile) }}
+  {#
+      "extra_css_files" is an undocumented Read the Docs theme specific option.
+      There is no need to check for ``|attr("filename")`` here because it's always a string.
+      Note that this option should be removed in favor of regular ``html_css_files``:
+      https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files
+  #}
+  {%- for css_file in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
   {%- endfor -%}
 
-  {#- FAVICON
-      favicon_url is the only context var necessary since Sphinx 4.
-      In Sphinx<4, we use favicon but need to prepend path info.
-  #}
-  {%- set _favicon_url = favicon_url | default(pathto('_static/' + (favicon or ""), 1)) %}
-  {%- if favicon_url or favicon %}
-    <link rel="shortcut icon" href="{{ _favicon_url }}"/>
+  {#- FAVICON #}
+  {%- if favicon_url %}
+    <link rel="shortcut icon" href="{{ favicon_url }}"/>
   {%- endif %}
 
   {#- CANONICAL URL (deprecated) #}
@@ -57,36 +61,16 @@
 
   {#- JAVASCRIPTS #}
   {%- block scripts %}
-  <!--[if lt IE 9]>
-    <script src="{{ pathto('_static/js/html5shiv.min.js', 1) }}"></script>
-  <![endif]-->
   {%- if not embedded %}
-  {# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #}
-    {%- if sphinx_version_info >= (1, 8) -%}
-      {%- if sphinx_version_info < (4, 0) -%}
-      <script id="documentation_options" data-url_root="{{ url_root }}" src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
-      {%- endif -%}
-      {%- for scriptfile in script_files %}
-        {{ js_tag(scriptfile) }}
-      {%- endfor %}
-    {%- else %}
-      <script>
-          var DOCUMENTATION_OPTIONS = {
-              URL_ROOT:'{{ url_root }}',
-              VERSION:'{{ release|e }}',
-              LANGUAGE:'{{ language }}',
-              COLLAPSE_INDEX:false,
-              FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
-              HAS_SOURCE:  {{ has_source|lower }},
-              SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}'
-          };
-      </script>
-      {%- for scriptfile in script_files %}
-        <script src="{{ pathto(scriptfile, 1) }}"></script>
-      {%- endfor %}
-    {%- endif %}
+    {%- for scriptfile in script_files %}
+      {{ js_tag(scriptfile) }}
+    {%- endfor %}
     <script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
 
+    {%- if READTHEDOCS or DEBUG %}
+    <script src="{{ pathto('_static/js/versions.js', 1) }}"></script>
+    {%- endif %}
+
     {#- OPENSEARCH #}
     {%- if use_opensearch %}
     <link rel="search" type="application/opensearchdescription+xml"
@@ -140,14 +124,11 @@
             {%- endif %}
           </a>
 
-          {%- if theme_display_version %}
-            {%- set nav_version = version %}
-            {%- if READTHEDOCS and current_version %}
-              {%- set nav_version = current_version %}
-            {%- endif %}
-            {%- if nav_version %}
-              <div class="version">
-                {{ nav_version }}
+          {%- if READTHEDOCS or DEBUG %}
+            {%- if theme_version_selector or theme_language_selector %}
+              <div class="switch-menus">
+                <div class="version-switch"></div>
+                <div class="language-switch"></div>
               </div>
             {%- endif %}
           {%- endif %}

sphinx_rtd_theme/static/css/badge_only.css

@@ -1 +1 @@
-.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}
+.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}

sphinx_rtd_theme/static/css/theme.css

@@ -1,4 +1,4 @@
 html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*!
  *  Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome
  *  License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
- */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-coLine truncated
+ */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-coLine truncated

sphinx_rtd_theme/static/js/versions.js_t

@@ -0,0 +1,228 @@
+const themeFlyoutDisplay = "{{ theme_flyout_display }}";
+const themeVersionSelector = {{ 'true' if theme_version_selector|tobool else 'false' }};
+const themeLanguageSelector = {{ 'true' if theme_language_selector|tobool else 'false' }};
+
+if (themeFlyoutDisplay === "attached") {
+  function renderLanguages(config) {
+    if (!config.projects.translations.length) {
+      return "";
+    }
+
+    // Insert the current language to the options on the selector
+    let languages = config.projects.translations.concat(config.projects.current);
+    languages = languages.sort((a, b) => a.language.name.localeCompare(b.language.name));
+
+    const languagesHTML = `
+      <dl>
+        <dt>{{ _('Languages') }}</dt>
+        ${languages
+          .map(
+            (translation) => `
+        <dd ${translation.slug == config.projects.current.slug ? 'class="rtd-current-item"' : ""}>
+          <a href="${translation.urls.documentation}">${translation.language.code}</a>
+        </dd>
+        `,
+          )
+          .join("\n")}
+      </dl>
+    `;
+    return languagesHTML;
+  }
+
+  function renderVersions(config) {
+    if (!config.versions.active.length) {
+      return "";
+    }
+    const versionsHTML = `
+      <dl>
+        <dt>{{ _('Versions') }}</dt>
+        ${config.versions.active
+          .map(
+            (version) => `
+        <dd ${version.slug === config.versions.current.slug ? 'class="rtd-current-item"' : ""}>
+          <a href="${version.urls.documentation}">${version.slug}</a>
+        </dd>
+        `,
+          )
+          .join("\n")}
+      </dl>
+    `;
+    return versionsHTML;
+  }
+
+  function renderDownloads(config) {
+    if (!Object.keys(config.versions.current.downloads).length) {
+      return "";
+    }
+    const downloadsNameDisplay = {
+      pdf: "PDF",
+      epub: "Epub",
+      htmlzip: "HTML",
+    };
+
+    const downloadsHTML = `
+      <dl>
+        <dt>{{ _('Downloads') }}</dt>
+        ${Object.entries(config.versions.current.downloads)
+          .map(
+            ([name, url]) => `
+          <dd>
+            <a href="${url}">${downloadsNameDisplay[name]}</a>
+          </dd>
+        `,
+          )
+          .join("\n")}
+      </dl>
+    `;
+    return downloadsHTML;
+  }
+
+  document.addEventListener("readthedocs-addons-data-ready", function (event) {
+    const config = event.detail.data();
+
+    const flyout = `
+      <div class="rst-versions" data-toggle="rst-versions" role="note">
+        <span class="rst-current-version" data-toggle="rst-current-version">
+          <span class="fa fa-book"> Read the Docs</span>
+          v: ${config.versions.current.slug}
+          <span class="fa fa-caret-down"></span>
+        </span>
+        <div class="rst-other-versions">
+          <div class="injected">
+            ${renderLanguages(config)}
+            ${renderVersions(config)}
+            ${renderDownloads(config)}
+            <dl>
+              <dt>{{ _('On Read the Docs') }}</dt>
+              <dd>
+                <a href="${config.projects.current.urls.home}">{{ _('Project Home') }}</a>
+              </dd>
+              <dd>
+                <a href="${config.projects.current.urls.builds}">{{ _('Builds') }}</a>
+              </dd>
+              <dd>
+                <a href="${config.projects.current.urls.downloads}">{{ _('Downloads') }}</a>
+              </dd>
+            </dl>
+            <dl>
+              <dt>{{ _('Search') }}</dt>
+              <dd>
+                <form id="flyout-search-form">
+                  <input
+                    class="wy-form"
+                    type="text"
+                    name="q"
+                    aria-label="{{ _('Search docs') }}"
+                    placeholder="{{ _('Search docs') }}"
+                    />
+                </form>
+              </dd>
+            </dl>
+            <hr />
+            <small>
+              <span>Hosted by <a href="https://about.readthedocs.org/?utm_source={{ READTHEDOCS_PROJECT }}&utm_content=flyout">Read the Docs</a></span>
+            </small>
+          </div>
+        </div>
+    `;
+
+    // Inject the generated flyout into the body HTML element.
+    document.body.insertAdjacentHTML("beforeend", flyout);
+
+    // Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout.
+    document
+      .querySelector("#flyout-search-form")
+      .addEventListener("focusin", () => {
+        const event = new CustomEvent("readthedocs-search-show");
+        document.dispatchEvent(event);
+      });
+  })
+}
+
+if (themeLanguageSelector || themeVersionSelector) {
+  function onSelectorSwitch(event) {
+    const option = event.target.selectedIndex;
+    const item = event.target.options[option];
+    window.location.href = item.dataset.url;
+  }
+
+  document.addEventListener("readthedocs-addons-data-ready", function (event) {
+    const config = event.detail.data();
+
+    const versionSwitch = document.querySelector(
+      "div.switch-menus > div.version-switch",
+    );
+    if (themeVersionSelector) {
+      let versions = config.versions.active;
+      if (config.versions.current.hidden || config.versions.current.type === "external") {
+        versions.unshift(config.versions.current);
+      }
+      const versionSelect = `
+    <select>
+      ${versions
+        .map(
+          (version) => `
+        <option
+  value="${version.slug}"
+  ${config.versions.current.slug === version.slug ? 'selected="selected"' : ""}
+              data-url="${version.urls.documentation}">
+              ${version.slug}
+          </option>`,
+        )
+        .join("\n")}
+    </select>
+  `;
+
+      versionSwitch.innerHTML = versionSelect;
+      versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
+    }
+
+    const languageSwitch = document.querySelector(
+      "div.switch-menus > div.language-switch",
+    );
+
+    if (themeLanguageSelector) {
+      if (config.projects.translations.length) {
+        // Add the current language to the options on the selector
+        let languages = config.projects.translations.concat(
+          config.projects.current,
+        );
+        languages = languages.sort((a, b) =>
+          a.language.name.localeCompare(b.language.name),
+        );
+
+        const languageSelect = `
+      <select>
+        ${languages
+          .map(
+            (language) => `
+              <option
+                  value="${language.language.code}"
+                  ${config.projects.current.slug === language.slug ? 'selected="selected"' : ""}
+                  data-url="${language.urls.documentation}">
+                  ${language.language.name}
+              </option>`,
+          )
+          .join("\n")}
+       </select>
+    `;
+
+        languageSwitch.innerHTML = languageSelect;
+        languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
+      }
+      else {
+        languageSwitch.remove();
+      }
+    }
+  });
+}
+
+document.addEventListener("readthedocs-addons-data-ready", function (event) {
+  // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
+  document
+    .querySelector("[role='search'] input")
+    .addEventListener("focusin", () => {
+      const event = new CustomEvent("readthedocs-search-show");
+      document.dispatchEvent(event);
+    });
+});

sphinx_rtd_theme/theme.conf

@@ -13,8 +13,10 @@ navigation_depth = 4
 includehidden = True
 titles_only =
 logo_only =
-display_version = True
 prev_next_buttons_location = bottom
 style_external_links = False
 style_nav_header_background =
 vcs_pageview_mode =
+flyout_display = hidden
+version_selector = True
+language_selector = True

sphinx_rtd_theme/versions.html

@@ -1,34 +0,0 @@
-{% if READTHEDOCS %}
-{# Add rst-badge after rst-versions for small badge style. #}
-  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="{{ _('Versions') }}">
-    <span class="rst-current-version" data-toggle="rst-current-version">
-      <span class="fa fa-book"> Read the Docs</span>
-      v: {{ current_version }}
-      <span class="fa fa-caret-down"></span>
-    </span>
-    <div class="rst-other-versions">
-      <dl>
-        <dt>{{ _('Versions') }}</dt>
-        {% for slug, url in versions %}
-          <dd><a href="{{ url }}">{{ slug }}</a></dd>
-        {% endfor %}
-      </dl>
-      <dl>
-        <dt>{{ _('Downloads') }}</dt>
-        {% for type, url in downloads %}
-          <dd><a href="{{ url }}">{{ type }}</a></dd>
-        {% endfor %}
-      </dl>
-      <dl>
-        {# Translators: The phrase "Read the Docs" is not translated #}
-        <dt>{{ _('On Read the Docs') }}</dt>
-          <dd>
-            <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _('Project Home') }}</a>
-          </dd>
-          <dd>
-            <a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _('Builds') }}</a>
-          </dd>
-      </dl>
-    </div>
-  </div>
-{% endif %}

src/sass/_theme_badge.sass

@@ -58,6 +58,8 @@
         display: inline-block
         padding: $base-line-height / 4
         color: $section-background-color
+    .rtd-current-item
+      font-weight: bold
   &.rst-badge
     width: auto
     bottom: 20px
@@ -92,3 +94,6 @@
     display: none
     &.shift
       display: block
+
+#flyout-search-form
+  padding: 6px

src/sass/_theme_layout.sass

@@ -217,7 +217,7 @@ html
     padding: ($base-line-height / 6) ($base-line-height / 4)
     margin-bottom: $gutter / 2
     max-width: 100%
-    &:hover
+    &:hover, &active, &focus
       background: rgba(255, 255, 255, 0.1)
     img.logo
       display: block  // display on its own line all the time
@@ -228,13 +228,57 @@ html
       max-width: 100%  // shrink on mobile, if appropriate
       background: rgba(0, 0, 0, 0)  // make hover background of parent show up properly
     &.icon
+      display: block
       img.logo
         margin-top: 0.85em  // space it away from the title text
-  > div.version
+  > div.switch-menus
+    position: relative
+    display: block
     margin-top: -1 * $gutter / 4
     margin-bottom: $gutter / 2
     font-weight: normal
-    color: rgba(255, 255, 255, 0.3)
+    color: rgba(255, 255,255, 0.3)
+    > div.version-switch, > div.language-switch
+      display: inline-block
+      padding: .2em
+      select
+        // Provide room for dropdown icon
+        display: inline-block
+        margin-right: -2rem
+        padding-right: 2rem
+        max-width: $nav-desktop-width * .8
+        // Alter base select styles
+        text-align-last: center
+        background: none
+        border: none
+        border-radius: 0em
+        box-shadow: none
+        font-family: $base-font-family
+        font-size: 1em
+        font-weight: normal
+        color: rgba(255, 255, 255, .3)
+        cursor: pointer
+        // Allow for padding
+        appearance: none
+        -webkit-appearance: none
+        -moz-appearance: none
+        &:hover, &:active, &:focus
+          background: rgba(255, 255, 255, .1)
+          color: rgba(255, 255, 255, .5)
+        option
+          color: black
+      &:has(> select):after
+        display: inline-block
+        width: 1.5em
+        height: 100%
+        padding: .1em
+        content: "\f0d7"
+        font-size: 1em
+        line-height: 1.2em
+        font-family: FontAwesome
+        text-align: center
+        pointer-events: none
+        box-sizing: border-box
 
 .wy-nav .wy-menu-vertical
   header

src/sass/_theme_rst.sass

@@ -615,3 +615,5 @@
   .rst-content
     .sidebar
       width: 100%
+      float: none
+      margin-left: 0

tests/test_builders.py

@@ -18,7 +18,7 @@ from .util import build_all
 
 def test_basic():
     for (app, status, warning) in build_all('test-basic'):
-        assert app.env.get_doctree('index').traverse(addnodes.toctree)
+        assert app.env.get_doctree('index').findall(addnodes.toctree)
         content = open(os.path.join(app.outdir, 'index.html')).read()
 
         if isinstance(app.builder, DirectoryHTMLBuilder):
@@ -37,10 +37,13 @@ def test_basic():
             )
             assert search in content
         elif isinstance(app.builder, SingleFileHTMLBuilder):
+            internal_ref = '#document-foo'
+            if sphinx.version_info[:3] < (7, 3, 0):
+                internal_ref = 'index.html' + internal_ref
             search = (
                 '<ul>\n'
                 '<li class="toctree-l1">'
-                '<a class="reference internal" href="index.html#document-foo">foo</a>'
+                f'<a class="reference internal" href="{internal_ref}">foo</a>'
                 '</li>\n'
                 '</ul>'
             )
@@ -66,7 +69,7 @@ def test_basic():
 def test_empty():
     """Local TOC is showing, as toctree was empty"""
     for (app, status, warning) in build_all('test-empty'):
-        assert app.env.get_doctree('index').traverse(addnodes.toctree)
+        assert app.env.get_doctree('index').findall(addnodes.toctree)
         content = open(os.path.join(app.outdir, 'index.html')).read()
         global_toc = '<div class="toctree-wrapper compound">\n</div>'
         local_toc = (
@@ -81,7 +84,7 @@ def test_empty():
 def test_missing_toctree():
     """Local TOC is showing, as toctree was missing"""
     for (app, status, warning) in build_all('test-missing-toctree'):
-        assert app.env.get_doctree('index').traverse(addnodes.toctree) == []
+        assert list(app.env.get_doctree('index').findall(addnodes.toctree)) == []
         content = open(os.path.join(app.outdir, 'index.html')).read()
         assert '<div class="toctree' not in content
         assert '<div class="local-toc">' in content

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',
-                    'readthedocssinglehtml', 'readthedocssinglehtmllocalmedia']:
+    for builder in ['html', 'singlehtml']:
         with build(root, builder, **kwargs) as ret:
             yield ret

tox.ini

@@ -1,30 +1,28 @@
 [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 3.11 working from Sphinx 5.3 and up
-    py{311}-sphinx{53,60,61,62,70,71,72,latest,dev}{-qa}
+    py{39,310,311,312,313}-sphinx{72,73,74,80}{-qa}
+    py{311}-sphinx{81,82,90,latest}{-qa}
+    py{312,313}-sphinx{81,82,90,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
+    sphinx81: Sphinx>=8.1,<8.2
+    sphinx82: Sphinx>=8.2,<8.3
+    sphinx90: Sphinx>=9.0,<9.1
     sphinxlatest: Sphinx
-    dev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
+    sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
 allowlist_externals =
     echo
 commands =

webpack.common.js

@@ -1,6 +1,5 @@
 const path = require("path");
 const MiniCssExtractPlugin = require("mini-css-extract-plugin");
-const CopyPlugin = require('copy-webpack-plugin');
 
 module.exports = {
   entry: {
@@ -66,11 +65,5 @@ module.exports = {
       filename: "css/[name].css?[hash]",
       chunkFilename: "css/[name].css?[hash]"
     }),
-    new CopyPlugin([
-      {
-        from: 'node_modules/html5shiv/dist/*.min.js',
-        flatten: true,
-        to: path.resolve(__dirname,'sphinx_rtd_theme/static/js') },
-    ]),
   ]
 };