Development

The theme developers follow the guidelines below for development and release planning. Documentation authors can decide which theme release works best for their project based on required browser/operating system combinations or dependency support.

Supported browsers

Official browser support is determined by the most popular browser/operating system combinations in our pageview analytics. Officially supported combinations are commonly tested during development, and are always tested before final release of a new version of the theme.

Older releases of supported combinations, and some less common combinations, are considered partially supported. This means that we do not consistently test these combinations, however we do expect user experience to be comparable with supported combinations.

Supported browser combinations
Browser	Operating System	Versions
Chrome	Windows, MacOS, Linux, Android	>=90
Firefox	Linux, Windows	>=90
Edge	Windows	>=90
Safari	MacOS, iOS	>=13

New in version 1.0: Supported browser and operating system combinations added

There are several browser/operating system combinations that are not supported by the theme developers at all. Unsupported combinations do not receive testing or development, and we likely won’t accept major contributions for these 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 3.0.0 release.
Opera (any OS, any version): Community support only. We do not receive enough traffic with this browser to officially support it in testing and development.

Supported dependencies

The theme officially supports the following dependencies in your Sphinx project:

Supported dependencies
Dependency	Versions
Python	3.6 or greater
Sphinx	5 or greater
docutils	>= 0.14, < 0.19

Deprecated since version 2.0: Sphinx < 5 support removed

Deprecated since version 2.0: Python < 3.6 support removed

Deprecated since version 2.0: docutils < 0.14 support removed

New in version 1.0: Sphinx 4.0 support added

Deprecated since version 1.0: Sphinx 1.6 support removed

New in version 1.0: docutils 0.17 support added

Roadmap

We currently have several releases planned on our development roadmap. Backward incompatible changes, deprecations, and major features are noted for each of these releases.

Releases follow semantic versioning, and so it is generally recommended that authors pin dependency on sphinx_rtd_theme to a version below the next major version:

$ pip install "sphinx_rtd_theme<2.0.0"

1.0.0

Planned release date:: August 2021

This release will be a slightly backwards incompatible release to follow the 0.5.2 release. It will drop support for Sphinx 1.6, which is a rather old release at this point.

This version will add official support for the Sphinx 4.x release series and it resolves bugs with the latest release of Docutils, version 0.17.

Starting with this release, several deprecation warnings will be emitted at build time:

Direct installation is deprecated

Support for direct installation through GitHub is no longer a suggested installation method. In an effort to ease maintenance, compiled assets will eventually be removed from the theme repository. These files will only be included in the built packages/releases available on PyPI.

We plan to start putting development releases up on PyPI more frequently, so that installation from the theme source repository is no longer necessary.

Built assets are tentatively planned to be removed in version 3.0.0:.

HTML4 support is deprecated

Support for the Sphinx HTML4 writer will be removed in the 2.0.0 release.

1.1.0

Planned release date:: 2021 Q3

We aim to follow up release 1.0.0 with at least one bug fix release in the 1.x release series. The 1.1 release will not be adding any major features and will instead mark the last release targeting projects with old dependencies like Sphinx 1.8, HTML4, or required support for IE11.

2.0.0

Planned release date:: 2023 Q3

This release will drop support for old Python and Sphinx versions.

Note the following backwards incompatible changes are planned for this release:

Python < 3.6, Sphinx < 5 and Docutils < 0.14 will not be tested

Official support will drop for these version, though they may still continue to work. Theme developers will not be testing these versions any longer.

HTML4 support will be removed

Starting with this release, we will only support the HTML5 writer output, and builds attempting to use the HTML4 writer will fail. If you are still using the HTML4 writer, or have the html4_writer = True option in your Sphinx configuration file, you will need to either remove this option or pin your dependency to sphinx_rtd_theme<=3 until you can.

This option was suggested in the past to work around issues with HTML5 support and should no longer be required to use a modern combination of this theme and Sphinx.

3.0.0

Planned release date:: 2024 Q1

This release is not yet fully planned. However, we already know that we will be dropping support for older version of different dependencies and browsers.

Sphinx 5, Python < 3.8 and docutils < 0.18 support will be removed: Sphinx 5 is the latest version that supports Python 3.6 and 3.7, and docutils < 0.18.
Internet Explorer 11 support will be dropped: IE11 reached end of life on 14 June 20222, so we are not supporting it on newer versions, starting on 3.0.0.

4.0.0

Planned release date:: 2024 Q2

This release is not yet planned. There are plans to potentially replace Wyrm with Bootstrap in a release after 3.0.

Also tentatively planned for this release is finally removing built CSS and JavaScript assets from our repository. This will remove the ability to install the package directly from GitHub, and instead users will be advised to install development releases from PyPI.