Merge pull request #1208 from readthedocs/agj/docs-development

Add development and usage documentation

7 files changed, 314 insertions, 67 deletions

diff --git a/README.rst b/README.rst
index dcc16cd..6925ece 100644
--- a/README.rst
+++ b/README.rst
@@ -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
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 36ff61e..1d7c065 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -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
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 3a5be79..9eedb03 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -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/
diff --git a/docs/development.rst b/docs/development.rst
new file mode 100644
index 0000000..1f2ed76
--- /dev/null
+++ b/docs/development.rst
@@ -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
diff --git a/docs/index.rst b/docs/index.rst
index 615fd93..28bb8c0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -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
diff --git a/docs/installing.rst b/docs/installing.rst
index 61aaac1..522b986 100644
--- a/docs/installing.rst
+++ b/docs/installing.rst
@@ -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.
diff --git a/docs/supported-browsers.csv b/docs/supported-browsers.csv
new file mode 100644
index 0000000..7e446d9
--- /dev/null
+++ b/docs/supported-browsers.csv
@@ -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