mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2026-10-12 09:24:51 -05:00
Add development and usage documentation
This finally defines our supported browsers and dependencies publicly, and communicates our next several versions that we have planned so far. This information is starting with 1.0.0, but I did try to capture some historical information as well.
This commit is contained in:
5 files changed
+230
-39
No files matched your search
+48
-38
@@ -59,8 +59,10 @@ Other Changes
|
||||
* Use regular toctree instead of toc for singlehtml builder (#507)
|
||||
* Cleanup whitespace in templates (#1060)
|
||||
|
||||
v0.5.2
|
||||
======
|
||||
.. _0.5.2:
|
||||
|
||||
0.5.2
|
||||
=====
|
||||
|
||||
:Date: April 5, 2021
|
||||
|
||||
@@ -69,8 +71,10 @@ v0.5.2
|
||||
|
||||
* Depend on docutils < 0.17 (#1113)
|
||||
|
||||
v0.5.1
|
||||
======
|
||||
.. _0.5.1:
|
||||
|
||||
0.5.1
|
||||
=====
|
||||
|
||||
:Date: January 4, 2021
|
||||
|
||||
@@ -99,8 +103,10 @@ Other Changes
|
||||
* Make Copyright template match sphinx's basic (#933)
|
||||
* Packaging: include ``bin/preinstall.js`` (#1005)
|
||||
|
||||
v0.5.0
|
||||
======
|
||||
.. _0.5.0:
|
||||
|
||||
0.5.0
|
||||
=====
|
||||
|
||||
:Date: Jun 17, 2020
|
||||
|
||||
@@ -109,8 +115,8 @@ Fixes
|
||||
|
||||
* Fix bullet list spacing to respect simple/complex list styles
|
||||
|
||||
v0.5.0rc2
|
||||
=========
|
||||
0.5.0rc2
|
||||
========
|
||||
|
||||
:Date: June 5, 2020
|
||||
|
||||
@@ -122,8 +128,8 @@ Fixes
|
||||
* Fix several margin issues with lists, nested lists, and nested content
|
||||
* Add colon back to field lists
|
||||
|
||||
v0.5.0rc1
|
||||
=========
|
||||
0.5.0rc1
|
||||
========
|
||||
|
||||
:Date: May 6, 2020
|
||||
|
||||
@@ -141,8 +147,10 @@ Other Changes
|
||||
* Moved build system from Grunt and friends to Webpack
|
||||
* Remove Modernizr, but keep html5shiv (#724, #525)
|
||||
|
||||
v0.4.3
|
||||
======
|
||||
.. _0.4.3:
|
||||
|
||||
0.4.3
|
||||
=====
|
||||
|
||||
:Date: Feb 12, 2019
|
||||
|
||||
@@ -161,8 +169,10 @@ Fixes
|
||||
Other Changes
|
||||
--------------
|
||||
|
||||
v0.4.2
|
||||
======
|
||||
.. _0.4.2:
|
||||
|
||||
0.4.2
|
||||
=====
|
||||
|
||||
:Date: Oct 5, 2018
|
||||
|
||||
@@ -181,8 +191,8 @@ Other Changes
|
||||
* Upload signed packages to PyPI with twine (#651)
|
||||
* Do not enforce period at the end of copyright statement (666)
|
||||
|
||||
v0.4.1
|
||||
======
|
||||
0.4.1
|
||||
=====
|
||||
|
||||
:Date: July 27, 2018
|
||||
|
||||
@@ -199,8 +209,8 @@ Other Changes
|
||||
|
||||
* Add Sphinx as a dependency
|
||||
|
||||
v0.4.0
|
||||
======
|
||||
0.4.0
|
||||
=====
|
||||
|
||||
This version made some changes to how JS and CSS were included
|
||||
when the theme is used on Read the Docs.
|
||||
@@ -222,8 +232,8 @@ Other Changes
|
||||
* Changed code and literals to use a native font stack (#612)
|
||||
* Fix small styling issues
|
||||
|
||||
v0.3.1
|
||||
======
|
||||
0.3.1
|
||||
=====
|
||||
|
||||
Fixes
|
||||
-----
|
||||
@@ -234,8 +244,8 @@ Fixes
|
||||
* Add open list spacing (#591)
|
||||
* Fix table centering (#599)
|
||||
|
||||
v0.3.0
|
||||
======
|
||||
0.3.0
|
||||
=====
|
||||
|
||||
**Note**: this version resulted in some JavaScript incompatibilities when used on readthedocs.org
|
||||
|
||||
@@ -268,40 +278,40 @@ Other Changes
|
||||
* Compress our Javascript files
|
||||
* Updated dependencies
|
||||
|
||||
v0.2.4
|
||||
======
|
||||
0.2.4
|
||||
=====
|
||||
|
||||
* Yet another patch to deal with extra builders outside Spinx, such as the
|
||||
singlehtml builders from the Read the Docs Sphinx extension
|
||||
|
||||
v0.2.3
|
||||
======
|
||||
0.2.3
|
||||
=====
|
||||
|
||||
* Temporarily patch Sphinx issue with ``singlehtml`` builder by inspecting the
|
||||
builder in template.
|
||||
|
||||
v0.2.2
|
||||
======
|
||||
0.2.2
|
||||
=====
|
||||
|
||||
* Roll back toctree fix in 0.2.1 (#367). This didn't fix the issue and
|
||||
introduced another bug with toctrees display.
|
||||
|
||||
v0.2.1
|
||||
======
|
||||
0.2.1
|
||||
=====
|
||||
|
||||
* Add the ``rel`` HTML attribute to the footer links which point to
|
||||
the previous and next pages.
|
||||
* Fix toctree issue caused by Sphinx singlehtml builder (#367)
|
||||
|
||||
v0.2.0
|
||||
======
|
||||
0.2.0
|
||||
=====
|
||||
|
||||
* Adds the ``comments`` block after the ``body`` block in the template
|
||||
* Added "Edit on GitLab" support
|
||||
* Many bug fixes
|
||||
|
||||
v0.1.10-alpha
|
||||
=============
|
||||
0.1.10-alpha
|
||||
============
|
||||
|
||||
.. note:: This is a pre-release version
|
||||
|
||||
@@ -310,8 +320,8 @@ v0.1.10-alpha
|
||||
* Adds a ``body_begin`` block to the template
|
||||
* Added ``prev_next_buttons_location``
|
||||
|
||||
v0.1.9
|
||||
======
|
||||
0.1.9
|
||||
=====
|
||||
|
||||
* Intermittent scrollbar visibility bug fixed. This change introduces a
|
||||
backwards incompatible change to the theme's layout HTML. This should only be
|
||||
@@ -327,8 +337,8 @@ v0.1.9
|
||||
|
||||
.. _#215: https://github.com/rtfd/sphinx_rtd_theme/pull/215
|
||||
|
||||
v0.1.8
|
||||
======
|
||||
0.1.8
|
||||
=====
|
||||
|
||||
* Start keeping changelog :)
|
||||
* Support for third and fourth level headers in the sidebar
|
||||
|
||||
@@ -175,7 +175,7 @@ To release a new version of the theme, core team will take the following steps:
|
||||
#. Bump the version by running ``bump2version [major|minor|patch|dev]``.
|
||||
This will automatically increase the correct part(s) of the version number,
|
||||
you do not need to specify the exact version number.
|
||||
We follow `semver <http://semver.org/>`_ and `PEP440`_
|
||||
We follow `semantic versioning`_ and `PEP440`_
|
||||
(with regards to alpha release and development versions). The version
|
||||
increment should reflect these releases and any potentially breaking changes.
|
||||
#. New versions are by default ``alpha`` releases. If this is a release candidate,
|
||||
@@ -202,3 +202,4 @@ To release a new version of the theme, core team will take the following steps:
|
||||
this change.
|
||||
|
||||
.. _PEP440: https://www.python.org/dev/peps/pep-0440/
|
||||
.. _semantic versioning: http://semver.org/
|
||||
@@ -0,0 +1,174 @@
|
||||
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.
|
||||
|
||||
.. 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
|
||||
----------------------
|
||||
|
||||
The theme officially supports the following dependencies in your Sphinx project:
|
||||
|
||||
.. list-table:: Supported dependencies
|
||||
:header-rows: 1
|
||||
:widths: 10, 10
|
||||
|
||||
* - Dependency
|
||||
- Versions
|
||||
* - 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/
|
||||
|
||||
.. _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:
|
||||
|
||||
Direction 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.
|
||||
|
||||
.. _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.
|
||||
|
||||
.. _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.
|
||||
|
||||
.. _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
|
||||
@@ -6,6 +6,7 @@
|
||||
|
||||
installing
|
||||
configuring
|
||||
development
|
||||
contributing
|
||||
|
||||
.. toctree::
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
Browser,Operating System,Versions
|
||||
Chrome,"Windows, MacOS, Linux, Android",>=90
|
||||
Firefox,"Linux, Windows",>=90
|
||||
Edge,Windows,>=90
|
||||
Safari,"MacOS, iOS",>=13
|
||||
|
Reference in new issue
Block a user