mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
b557851511
Perhaps this is a feature of Sphinx I'm not aware of, but using a version number as the section label resulted in ``#id1`` instead. I tried autosectionlabel, but as expected there were a lot of errors and I don't feel it's worthwhile to spend time fixing them right now.
181 lines
5.8 KiB
ReStructuredText
181 lines
5.8 KiB
ReStructuredText
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:`2.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
|
|
- 2.7 or 3.6 or greater
|
|
* - Sphinx
|
|
- 1.7 up to at least 4.1
|
|
* - docutils
|
|
- Up to 0.17
|
|
|
|
.. 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/
|
|
|
|
.. _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:`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:`3.0.0`:.
|
|
|
|
HTML4 support is deprecated
|
|
Support for the Sphinx HTML4 writer will be removed in the :ref:`2.0.0`
|
|
release.
|
|
|
|
.. _release-1.1.0:
|
|
|
|
1.1.0
|
|
~~~~~
|
|
|
|
:Planned release date: 2021 Q3
|
|
|
|
We aim to follow up release :ref:`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.
|
|
|
|
.. _release-2.0.0:
|
|
|
|
2.0.0
|
|
~~~~~
|
|
|
|
:Planned release date: 2022 Q1
|
|
|
|
This release will mark the beginning of a new round of feature development, as
|
|
well as a number of backward incompatible changes and deprecations.
|
|
|
|
Of note, the following backwards incompatible changes are planned for this
|
|
release:
|
|
|
|
Sphinx 1.x, Sphinx 2.x, and Docutils 0.16 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<=2.0.0`` 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.
|
|
|
|
.. _release-3.0.0:
|
|
|
|
3.0.0
|
|
~~~~~
|
|
|
|
This release is not yet planned, however there are plans to potentially replace
|
|
Wyrm with Bootstrap in a release after 2.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
|