Development
The theme developers follow the guidelines below for development and releaseplanning. Documentation authors can decide which theme release works best fortheir project based on required browser/operating system combinations ordependency support.
Supported browsers
Official browser support is determined by the most popular browser/operatingsystem combinations in our pageview analytics. Officially supported combinationsare commonly tested during development, and are always tested before finalrelease of a new version of the theme.
Older releases of supported combinations, and some less common combinations, areconsidered partially supported. This means that we do not consistently testthese combinations, however we do expect user experience to be comparable withsupported 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 supportedby the theme developers at all. Unsupported combinations do not receive testingor development, and we likely won’t accept major contributions for thesecombinations.
Unsupported browser/operating system combinations include:
- Internet Explorer (any OS, any version)
Support was removed in the3.0.0 release.
- Opera (any OS, any version)
Community support only. We do not receive enough traffic with thisbrowser to officially support it in testing and development.
Supported dependencies
The theme officially supports the following dependencies in your Sphinx project:
Dependency | Versions |
|---|---|
Python | 3.8 or greater |
Sphinx | 6 or greater |
docutils | > 0.18, < 0.22 |
Deprecated since version 3.0:Sphinx < 6 support removed
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. Backwardincompatible changes, deprecations, and major features are noted for each ofthese releases.
Releases followsemantic versioning, and so it is generally recommended thatauthors pin dependency onsphinx_rtd_theme to a version below the next majorversion:
$pipinstall"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 the0.5.2 release. It will drop support for Sphinx 1.6, which is a rather oldrelease at this point.
This version will add official support for the Sphinx 4.x release series andit resolves bugs with the latest release of Docutils, version 0.17.
Starting with this release, several deprecation warnings will be emitted atbuild time:
- Direct installation is deprecated
Support for direct installation through GitHub is no longer a suggestedinstallation method. In an effort to ease maintenance, compiled assets willeventually be removed from the theme repository. These files will only beincluded in the built packages/releases available on PyPI.
We plan to start putting development releases up on PyPI more frequently, sothat installation from the theme source repository is no longer necessary.
Built assets are tentatively planned to be removed in version3.0.0:.
- HTML4 support is deprecated
Support for the Sphinx HTML4 writer will be removed in the2.0.0release.
1.1.0
- Planned release date:
2021 Q3
We aim to follow up release1.0.0 with at least one bug fix release inthe 1.x release series. The 1.1 release will not be adding any major featuresand will instead mark the last release targeting projects with old dependencieslike 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 thisrelease:
- Python < 3.6, Sphinx < 5 and Docutils < 0.14 will not be tested
Official support will drop for these version, though they may still continueto 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 stillusing the HTML4 writer, or have the
html4_writer=Trueoption in yourSphinx configuration file, you will need to either remove this option or pinyour dependency tosphinx_rtd_theme<=3until you can.This option was suggested in the past to work around issues with HTML5support and should no longer be required to use a modern combination of thistheme and Sphinx.
3.0.0
- Planned release date:
2024 Q3
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,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 andJavaScript assets from our repository. This will remove the ability to installthe package directly from GitHub, and instead users will be advised to installdevelopment releases from PyPI.