mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2026-10-12 09:24:51 -05:00
Merge pull request #1208 from readthedocs/agj/docs-development
Add development and usage documentation
This commit is contained in:
7 files changed
+314
-67
No files matched your search
+15
-6
@@ -22,7 +22,7 @@ a working demo of the theme in the `theme documentation`_
|
||||
|
||||
.. _Sphinx: http://www.sphinx-doc.org
|
||||
.. _Read the Docs: http://www.readthedocs.org
|
||||
.. _theme documentation: https://sphinx-rtd-theme.readthedocs.io/en/latest/
|
||||
.. _theme documentation: https://sphinx-rtd-theme.readthedocs.io/en/stable/
|
||||
|
||||
Installation
|
||||
============
|
||||
@@ -40,11 +40,20 @@ your ``conf.py`` file's ``html_theme`` setting:
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
|
||||
For more information, including a full example with localized strings enabled,
|
||||
read the documentation on `installing the theme`_.
|
||||
.. seealso::
|
||||
`Supported browsers`_
|
||||
Officially supported and tested browser/operating system combinations
|
||||
|
||||
`Supported dependencies`_
|
||||
Supported versions of Python, Sphinx, and other dependencies.
|
||||
|
||||
`Example documentation`_
|
||||
A full example of this theme output, with localized strings enabled.
|
||||
|
||||
.. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
|
||||
.. _installing the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html
|
||||
.. _Supported browsers: https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#supported-browsers
|
||||
.. _Supported dependencies: https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#supported-dependencies
|
||||
.. _Example documentation: https://sphinx-rtd-theme.readthedocs.io/en/stable/
|
||||
|
||||
Configuration
|
||||
=============
|
||||
@@ -53,7 +62,7 @@ This theme is highly customizable on both the page level and on a global level.
|
||||
To see all the possible configuration options, read the documentation on
|
||||
`configuring the theme`_.
|
||||
|
||||
.. _configuring the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html
|
||||
.. _configuring the theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
|
||||
|
||||
Contributing
|
||||
============
|
||||
@@ -61,4 +70,4 @@ Contributing
|
||||
If you would like to help modify or translate the theme, you'll find more
|
||||
information on contributing in our `contributing guide`_.
|
||||
|
||||
.. _contributing guide: https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html
|
||||
.. _contributing guide: https://sphinx-rtd-theme.readthedocs.io/en/stable/contributing.html
|
||||
+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,180 @@
|
||||
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/
|
||||
|
||||
.. _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.
|
||||
|
||||
.. _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
|
||||
+53
-1
@@ -1,11 +1,61 @@
|
||||
.. include:: ../README.rst
|
||||
Read the Docs Sphinx Theme
|
||||
==========================
|
||||
|
||||
This Sphinx_ theme was designed to provide a great reader experience for
|
||||
documentation users on both desktop and mobile devices. This theme is commonly
|
||||
used with projects on `Read the Docs`_ but can work with any Sphinx project.
|
||||
|
||||
.. _Sphinx: http://www.sphinx-doc.org
|
||||
.. _Read the Docs: http://www.readthedocs.org
|
||||
|
||||
Using this theme
|
||||
----------------
|
||||
|
||||
:doc:`installing`
|
||||
How to install this theme on your Sphinx project.
|
||||
|
||||
:doc:`configuring`
|
||||
Theme configuration and customization options.
|
||||
|
||||
:ref:`supported-browsers`
|
||||
Supported browser/operating system combinations.
|
||||
|
||||
:ref:`supported-dependencies`
|
||||
Supported project dependencies, like Python and Sphinx.
|
||||
|
||||
Development
|
||||
-----------
|
||||
|
||||
:doc:`contributing`
|
||||
How to contribute changes to the theme.
|
||||
|
||||
:doc:`Development guidelines <development>`
|
||||
Guidelines the theme developers use for developing and testing changes.
|
||||
|
||||
`Read the Docs contributor guide`_
|
||||
Our contribution guidelines extend to all projects maintained by Read the
|
||||
Docs core team.
|
||||
|
||||
:doc:`changelog`
|
||||
The theme development changelog.
|
||||
|
||||
:doc:`Demo documentation <demo/structure>`
|
||||
The theme's styleguide test environment, where new changes are tested.
|
||||
|
||||
|
||||
.. _Read the Docs contributor guide: https://docs.readthedocs.io/en/stable/contribute.html
|
||||
|
||||
|
||||
.. Hidden TOCs
|
||||
|
||||
.. toctree::
|
||||
:caption: Theme Documentation
|
||||
:maxdepth: 2
|
||||
:hidden:
|
||||
|
||||
installing
|
||||
configuring
|
||||
development
|
||||
contributing
|
||||
|
||||
.. toctree::
|
||||
@@ -18,6 +68,7 @@
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
:caption: Demo Documentation
|
||||
:hidden:
|
||||
|
||||
demo/structure
|
||||
demo/demo
|
||||
@@ -28,5 +79,6 @@
|
||||
:maxdepth: 3
|
||||
:numbered:
|
||||
:caption: This is an incredibly long caption for a long menu
|
||||
:hidden:
|
||||
|
||||
demo/long
|
||||
+11
-21
@@ -1,6 +1,5 @@
|
||||
************
|
||||
Installation
|
||||
************
|
||||
============
|
||||
|
||||
Install the package (or add it to your ``requirements.txt`` file):
|
||||
|
||||
@@ -21,6 +20,12 @@ In your ``conf.py`` file:
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
|
||||
.. seealso::
|
||||
:ref:`supported-browsers`
|
||||
Officially supported and tested browser/operating system combinations
|
||||
|
||||
:ref:`supported-dependencies`
|
||||
Officially Supported versions of Python, Sphinx, and other dependencies.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -30,12 +35,13 @@ In your ``conf.py`` file:
|
||||
are using an old version of the theme.
|
||||
|
||||
Via Git or Download
|
||||
===================
|
||||
-------------------
|
||||
|
||||
.. warning::
|
||||
|
||||
Installing directly from the repo is deprecated.
|
||||
Static assets won't be included in the repo in a future release.
|
||||
Installing directly from the repository source is deprecated and is not
|
||||
recommended. Static assets won't be included in the repository starting in
|
||||
release :ref:`3.0.0`.
|
||||
|
||||
Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
|
||||
``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
|
||||
@@ -45,19 +51,3 @@ Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into you
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
html_theme_path = ["_themes", ]
|
||||
|
||||
Compatibility
|
||||
=============
|
||||
|
||||
Python
|
||||
------
|
||||
|
||||
``sphinx_rtd_theme`` requires Python 2.7 or Python 3.4 or greater.
|
||||
|
||||
Sphinx
|
||||
------
|
||||
|
||||
``sphinx_rtd_theme`` depends on at least Sphinx 1.6 although,
|
||||
we recommend at least Sphinx 2 to take advantage of the html5 writer.
|
||||
The html4 writer is still supported however,
|
||||
it is deprecated and support will be removed in the near future.
|
||||
@@ -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