|
| 1 | +Development |
| 2 | +=========== |
| 3 | + |
| 4 | +The theme developers follow the guidelines below for development and release |
| 5 | +planning. Documentation authors can decide which theme release works best for |
| 6 | +their project based on required browser/operating system combinations or |
| 7 | +dependency support. |
| 8 | + |
| 9 | +Supported browsers |
| 10 | +------------------ |
| 11 | + |
| 12 | +Official browser support is determined by the most popular browser/operating |
| 13 | +system combinations in our pageview analytics. Officially supported combinations |
| 14 | +are commonly tested during development, and are always tested before final |
| 15 | +release of a new version of the theme. |
| 16 | + |
| 17 | +Older releases of supported combinations, and some less common combinations, are |
| 18 | +considered partially supported. This means that we do not consistently test |
| 19 | +these combinations, however we do expect user experience to be comparable with |
| 20 | +supported combinations. |
| 21 | + |
| 22 | +.. csv-table:: Supported browser combinations |
| 23 | + :widths: 6, 12, 4 |
| 24 | + :header-rows: 1 |
| 25 | + :file: supported-browsers.csv |
| 26 | + |
| 27 | +.. versionadded:: 1.0 |
| 28 | + Supported browser and operating system combinations added |
| 29 | + |
| 30 | +There are several browser/operating system combinations that are not supported |
| 31 | +by the theme developers at all. Unsupported combinations do not receive testing |
| 32 | +or development, and we likely won't accept major contributions for these |
| 33 | +combinations. |
| 34 | + |
| 35 | +Unsupported browser/operating system combinations include: |
| 36 | + |
| 37 | +Internet Explorer (any OS, versions <=10) |
| 38 | + **Unsupported.** IE11 is the last partially supported version. We do no |
| 39 | + testing on prior versions. |
| 40 | + |
| 41 | +Internet Explorer (any OS, version 11) |
| 42 | + We currently only partially support IE11, and only test for major bugs. |
| 43 | + Support will be removed in the :ref:`2.0.0` release. |
| 44 | + |
| 45 | +Opera (any OS, any version) |
| 46 | + **Community support only.** We do not receive enough traffic with this |
| 47 | + browser to officially support it in testing and development. |
| 48 | + |
| 49 | +Supported dependencies |
| 50 | +---------------------- |
| 51 | + |
| 52 | +The theme officially supports the following dependencies in your Sphinx project: |
| 53 | + |
| 54 | +.. list-table:: Supported dependencies |
| 55 | + :header-rows: 1 |
| 56 | + :widths: 10, 10 |
| 57 | + |
| 58 | + * - Dependency |
| 59 | + - Versions |
| 60 | + * - Sphinx |
| 61 | + - 1.7 up to at least 4.1 |
| 62 | + * - docutils |
| 63 | + - Up to 0.17 |
| 64 | + |
| 65 | +.. versionadded:: 1.0 |
| 66 | + Sphinx 4.0 support added |
| 67 | + |
| 68 | +.. deprecated:: 1.0 |
| 69 | + Sphinx 1.6 support removed |
| 70 | + |
| 71 | +.. versionadded:: 1.0 |
| 72 | + docutils 0.17 support added |
| 73 | + |
| 74 | +Roadmap |
| 75 | +------- |
| 76 | + |
| 77 | +We currently have several releases planned on our development roadmap. Backward |
| 78 | +incompatible changes, deprecations, and major features are noted for each of |
| 79 | +these releases. |
| 80 | + |
| 81 | +Releases follow `semantic versioning`_, and so it is generally recommended that |
| 82 | +authors pin dependency on ``sphinx_rtd_theme`` to a version below the next major |
| 83 | +version: |
| 84 | + |
| 85 | +.. code:: console |
| 86 | +
|
| 87 | + % pip install "sphinx_rtd_theme<=2.0.0" |
| 88 | +
|
| 89 | +.. _semantic versioning: http://semver.org/ |
| 90 | + |
| 91 | +.. _1.0.0: |
| 92 | + |
| 93 | +1.0.0 |
| 94 | +~~~~~ |
| 95 | + |
| 96 | +:Planned release date: August 2021 |
| 97 | + |
| 98 | +This release will be a slightly backwards incompatible release to follow the |
| 99 | +:ref:`0.5.2` release. It will drop support for Sphinx 1.6, which is a rather old |
| 100 | +release at this point. |
| 101 | + |
| 102 | +This version will add official support for the Sphinx 4.x release series and |
| 103 | +it resolves bugs with the latest release of Docutils, version 0.17. |
| 104 | + |
| 105 | +Starting with this release, several deprecation warnings will be emitted at |
| 106 | +build time: |
| 107 | + |
| 108 | +Direction installation is deprecated |
| 109 | + Support for direct installation through GitHub is no longer a suggested |
| 110 | + installation method. In an effort to ease maintenance, compiled assets will |
| 111 | + eventually be removed from the theme repository. These files will only be |
| 112 | + included in the built packages/releases available on PyPI. |
| 113 | + |
| 114 | + We plan to start putting development releases up on PyPI more frequently, so |
| 115 | + that installation from the theme source repository is no longer necessary. |
| 116 | + |
| 117 | + Built assets are tentatively planned to be removed in version :ref:`3.0.0`:. |
| 118 | + |
| 119 | +HTML4 support is deprecated |
| 120 | + Support for the Sphinx HTML4 writer will be removed in the :ref:`2.0.0` |
| 121 | + release. |
| 122 | + |
| 123 | +.. _1.1.0: |
| 124 | + |
| 125 | +1.1.0 |
| 126 | +~~~~~ |
| 127 | + |
| 128 | +:Planned release date: 2021 Q3 |
| 129 | + |
| 130 | +We aim to follow up release :ref:`1.0.0` with at least one bug fix release in |
| 131 | +the 1.x release series. The 1.1 release will not be adding any major features |
| 132 | +and will instead mark the last release targeting projects with old dependencies |
| 133 | +like Sphinx 1.8, HTML4, or required support for IE11. |
| 134 | + |
| 135 | +.. _2.0.0: |
| 136 | + |
| 137 | +2.0.0 |
| 138 | +~~~~~ |
| 139 | + |
| 140 | +:Planned release date: 2022 Q1 |
| 141 | + |
| 142 | +This release will mark the beginning of a new round of feature development, as |
| 143 | +well as a number of backward incompatible changes and deprecations. |
| 144 | + |
| 145 | +Of note, the following backwards incompatible changes are planned for this |
| 146 | +release: |
| 147 | + |
| 148 | +Sphinx 1.x, Sphinx 2.x, and Docutils 0.16 will not be tested |
| 149 | + Official support will drop for these version, though they may still continue |
| 150 | + to work. Theme developers will not be testing these versions any longer. |
| 151 | + |
| 152 | +HTML4 support will be removed |
| 153 | + Starting with this release, we will only support the HTML5 writer output, |
| 154 | + and builds attempting to use the HTML4 writer will fail. If you are still |
| 155 | + using the HTML4 writer, or have the ``html4_writer = True`` option in your |
| 156 | + Sphinx configuration file, you will need to either remove this option or pin |
| 157 | + your dependency to ``sphinx_rtd_theme<=2.0.0`` until you can. |
| 158 | + |
| 159 | + This option was suggested in the past to work around issues with HTML5 |
| 160 | + support and should no longer be required to use a modern combination of this |
| 161 | + theme and Sphinx. |
| 162 | + |
| 163 | +.. _3.0.0: |
| 164 | + |
| 165 | +3.0.0 |
| 166 | +~~~~~ |
| 167 | + |
| 168 | +This release is not yet planned, however there are plans to potentially replace |
| 169 | +Wyrm with Bootstrap in a release after 2.0. |
| 170 | + |
| 171 | +Also tentatively planned for this release is finally removing built CSS and |
| 172 | +JavaScript assets from our repository. This will remove the ability to install |
| 173 | +the package directly from GitHub, and instead users will be advised to install |
| 174 | +development releases from PyPI |
0 commit comments