1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
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:
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.
.. csv-table:: Supported browser combinations
:widths: 6, 12, 4
:header-rows: 1
:file: supported-browsers.csv
.. versionadded:: 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 :ref:`roadmap-release-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:
Supported dependencies
----------------------
The theme officially supports the following dependencies in your Sphinx project:
.. list-table:: Supported dependencies
:header-rows: 1
:widths: 10, 10
* - Dependency
- Versions
* - Python
- 3.6 or greater
* - Sphinx
- 5 or greater
* - docutils
- >= 0.14, < 0.19
.. deprecated:: 2.0
Sphinx < 5 support removed
.. deprecated:: 2.0
Python < 3.6 support removed
.. deprecated:: 2.0
docutils < 0.14 support removed
.. versionadded:: 1.0
Sphinx 4.0 support added
.. deprecated:: 1.0
Sphinx 1.6 support removed
.. versionadded:: 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:
.. code:: console
$ pip install "sphinx_rtd_theme<2.0.0"
.. _semantic versioning: http://semver.org/
.. _roadmap-release-1.0.0:
1.0.0
~~~~~
:Planned release date: August 2021
This release will be a slightly backwards incompatible release to follow the
:ref:`release-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 :ref:`roadmap-release-3.0.0`:.
HTML4 support is deprecated
Support for the Sphinx HTML4 writer will be removed in the :ref:`roadmap-release-2.0.0`
release.
.. _roadmap-release-1.1.0:
1.1.0
~~~~~
:Planned release date: 2021 Q3
We aim to follow up release :ref:`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.
.. _roadmap-release-2.0.0:
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.
.. _roadmap-release-3.0.0:
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 <https://endoflife.date/internet-explorer>`_,
so we are not supporting it on newer versions,
starting on 3.0.0.
.. _roadmap-release-4.0.0:
4.0.0
~~~~~
:Planned release date: 2024 Q2
This release is not yet planned.
There are plans to potentially replace Wyrm with Bootstrap in a release after 3.0.
Also tentatively planned for this release is finally removing built CSS and
JavaScript assets from our repository. This will remove the ability to install
the package directly from GitHub, and instead users will be advised to install
development releases from PyPI.
|
