From 8809321a6a24a96b14853d2cd7bbc74c804720a2 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 19 Aug 2022 18:40:29 +0200 Subject: [PATCH] Merge upstream/master, fix conflicts in src/sass/_theme_rst.sass --- .circleci/config.yml | 48 ++++- .github/CODEOWNERS | 1 + .gitignore | 4 + .tx/config | 2 +- README.rst | 30 +-- docs/changelog.rst | 155 +++++++++----- docs/conf.py | 8 +- docs/configuring.rst | 8 +- docs/contributing.rst | 90 +++++++- docs/demo/test_py_module/test.py | 21 ++ docs/development.rst | 180 ++++++++++++++++ docs/index.rst | 54 ++++- docs/installing.rst | 24 +-- docs/supported-browsers.csv | 5 + package-lock.json | 98 ++++----- package.json | 2 +- setup.cfg | 64 +++++- setup.py | 61 +----- sphinx_rtd_theme/__init__.py | 9 +- sphinx_rtd_theme/breadcrumbs.html | 6 +- sphinx_rtd_theme/footer.html | 5 +- sphinx_rtd_theme/layout.html | 56 +++-- .../locale/de/LC_MESSAGES/sphinx.mo | Bin 2085 -> 2085 bytes .../locale/de/LC_MESSAGES/sphinx.po | 48 ++--- .../locale/en/LC_MESSAGES/sphinx.mo | Bin 455 -> 455 bytes .../locale/en/LC_MESSAGES/sphinx.po | 85 +++++--- .../locale/es/LC_MESSAGES/sphinx.mo | Bin 2266 -> 2509 bytes .../locale/es/LC_MESSAGES/sphinx.po | 82 ++++---- .../locale/et/LC_MESSAGES/sphinx.mo | Bin 2059 -> 2378 bytes .../locale/et/LC_MESSAGES/sphinx.po | 77 ++++--- .../locale/fa_IR/LC_MESSAGES/sphinx.mo | Bin 0 -> 2704 bytes .../locale/fa_IR/LC_MESSAGES/sphinx.po | 160 +++++++++++++++ .../locale/fr/LC_MESSAGES/sphinx.mo | Bin 2164 -> 2493 bytes .../locale/fr/LC_MESSAGES/sphinx.po | 74 ++++--- .../locale/it/LC_MESSAGES/sphinx.mo | Bin 0 -> 2662 bytes .../locale/it/LC_MESSAGES/sphinx.po | 190 +++++++++++++++++ .../locale/lt/LC_MESSAGES/sphinx.mo | Bin 0 -> 2748 bytes .../locale/lt/LC_MESSAGES/sphinx.po | 188 +++++++++++++++++ .../locale/nl/LC_MESSAGES/sphinx.mo | Bin 2069 -> 2547 bytes .../locale/nl/LC_MESSAGES/sphinx.po | 94 ++++++--- .../locale/pl/LC_MESSAGES/sphinx.mo | Bin 0 -> 2337 bytes .../locale/pl/LC_MESSAGES/sphinx.po | 137 +++++++++++++ .../locale/pt/LC_MESSAGES/sphinx.mo | Bin 0 -> 2301 bytes .../locale/pt/LC_MESSAGES/sphinx.po | 161 +++++++++++++++ .../locale/pt_BR/LC_MESSAGES/sphinx.mo | Bin 2219 -> 2726 bytes .../locale/pt_BR/LC_MESSAGES/sphinx.po | 95 ++++++--- .../locale/ru/LC_MESSAGES/sphinx.mo | Bin 2791 -> 3447 bytes .../locale/ru/LC_MESSAGES/sphinx.po | 94 ++++++--- sphinx_rtd_theme/locale/sphinx.pot | 78 ++++--- .../locale/sv/LC_MESSAGES/sphinx.mo | Bin 2097 -> 2130 bytes .../locale/sv/LC_MESSAGES/sphinx.po | 57 +++--- .../locale/tr/LC_MESSAGES/sphinx.mo | Bin 2115 -> 2115 bytes .../locale/tr/LC_MESSAGES/sphinx.po | 49 +++-- .../locale/zh_CN/LC_MESSAGES/sphinx.mo | Bin 2056 -> 2082 bytes .../locale/zh_CN/LC_MESSAGES/sphinx.po | 61 +++--- sphinx_rtd_theme/search.html | 8 +- sphinx_rtd_theme/static/css/theme.css | 4 +- sphinx_rtd_theme/static/js/theme.js | 2 +- src/sass/_theme_badge_fa.sass | 2 +- src/sass/_theme_layout.sass | 58 +++--- src/sass/_theme_rst.sass | 193 +++++++++++------- src/sass/_theme_variables.sass | 4 +- src/theme.js | 40 +++- tests/test_builders.py | 10 +- tests/util.py | 1 + tox.ini | 8 +- 66 files changed, 2282 insertions(+), 709 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 docs/development.rst create mode 100644 docs/supported-browsers.csv create mode 100644 sphinx_rtd_theme/locale/fa_IR/LC_MESSAGES/sphinx.mo create mode 100644 sphinx_rtd_theme/locale/fa_IR/LC_MESSAGES/sphinx.po create mode 100644 sphinx_rtd_theme/locale/it/LC_MESSAGES/sphinx.mo create mode 100644 sphinx_rtd_theme/locale/it/LC_MESSAGES/sphinx.po create mode 100644 sphinx_rtd_theme/locale/lt/LC_MESSAGES/sphinx.mo create mode 100644 sphinx_rtd_theme/locale/lt/LC_MESSAGES/sphinx.po create mode 100644 sphinx_rtd_theme/locale/pl/LC_MESSAGES/sphinx.mo create mode 100644 sphinx_rtd_theme/locale/pl/LC_MESSAGES/sphinx.po create mode 100644 sphinx_rtd_theme/locale/pt/LC_MESSAGES/sphinx.mo create mode 100644 sphinx_rtd_theme/locale/pt/LC_MESSAGES/sphinx.po diff --git a/.circleci/config.yml b/.circleci/config.yml index 0d2636189..ae6709199 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,5 +1,8 @@ version: 2.1 +orbs: + node: circleci/node@5.0.2 + commands: run-tox: description: "Run tox" @@ -8,13 +11,35 @@ commands: type: string sphinx-version: type: string - default: "16,17,18,20,21,22,23,24,30,31,32,33,34,latest" + default: "16,17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,latest" steps: - checkout - run: pip install --user tox - run: tox -e "<>-sphinx{<>}" + run-build: + description: "Ensure built assets are up to date" + steps: + - checkout + - node/install: + node-version: '14.20' + - run: npm ci + - run: npm run build + - run: + name: Ensure built assets are up to date + command: | + if [[ `git status sphinx_rtd_theme/ --porcelain` ]] + then + echo "ERROR: assets are out of date. Make sure to run 'npm run build' on your branch." + git status sphinx_rtd_theme/ --porcelain + exit 1 + fi jobs: + build: + docker: + - image: 'cimg/python:3.9-node' + steps: + - run-build: {} py27: docker: - image: 'cimg/python:2.7' @@ -50,8 +75,19 @@ workflows: version: 2 tests: jobs: - - py39 - - py38 - - py37 - - py36 - - py27 + - build + - py39: + requires: + - build + - py38: + requires: + - build + - py37: + requires: + - build + - py36: + requires: + - build + - py27: + requires: + - build diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..8fa0ef8c0 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @readthedocs/theme diff --git a/.gitignore b/.gitignore index b7d50a023..9ddd50e5f 100644 --- a/.gitignore +++ b/.gitignore @@ -21,5 +21,9 @@ sphinx_rtd_theme/static/fonts/Lato/ sphinx_rtd_theme/static/fonts/RobotoSlab/ .python-version .node-version +.tool-versions +.nvmrc sphinx_rtd_theme/static/js/html5shiv.min.js sphinx_rtd_theme/static/js/html5shiv-printshiv.min.js +.direnv/ +.envrc diff --git a/.tx/config b/.tx/config index 516386007..1e4276410 100644 --- a/.tx/config +++ b/.tx/config @@ -2,7 +2,7 @@ file_filter = sphinx_rtd_theme/locale//LC_MESSAGES/sphinx.po source_file = sphinx_rtd_theme/locale/en/LC_MESSAGES/sphinx.po source_lang = en -minimum_perc = 90 +minimum_perc = 60 [main] host = https://www.transifex.com diff --git a/README.rst b/README.rst index dcc8078b0..f51d8b2e9 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 ============ @@ -33,24 +33,28 @@ This theme is distributed on PyPI_ and can be installed with ``pip``: $ pip install sphinx-rtd-theme -To use the theme in your Sphinx project, you will need to add the following to -your ``conf.py`` file: +To use the theme in your Sphinx project, you will need to edit +your ``conf.py`` file's ``html_theme`` setting: .. code:: python - import sphinx_rtd_theme + html_theme = "sphinx_rtd_theme" - extensions = [ - ... - "sphinx_rtd_theme", - ] +.. admonition:: See also: - html_theme = "sphinx_rtd_theme" + `Supported browsers`_ + Officially supported and tested browser/operating system combinations + + `Supported dependencies`_ + Supported versions of Python, Sphinx, and other dependencies. -For more information read the full documentation on `installing the theme`_ + `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 ============= @@ -59,7 +63,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 ============ @@ -67,4 +71,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 95ded7799..87422efda 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -2,11 +2,15 @@ Changelog ********* -master -====== +Development version (|development_version|) +=========================================== -v1.0.0 -====== +.. |development_version| replace:: 1.0.1alpha1 + +.. _release-1.0.0: + +1.0.0 +===== Incompatible Changes -------------------- @@ -17,7 +21,42 @@ Incompatible Changes Deprecated ---------- -* Support for sphinx's html4 writer is deprecated and will be removed in version 2.0 (#1091) +* Support for Sphinx's HTML4 writer is deprecated and will be removed in version 2.0 (#1091) + +Features +-------- + +* Add support for Sphinx 4.x (#1123) +* Add support for Docutils 0.17 (#1185 and #1199) +* Fixed logo scaling on IE11 (#1183) +* Added support for logos as URLs (#1171) +* Align top and side navigation background colors on mobile (#1132) +* Added support for deep toc levels (#1089) +* Updated translations for Chinese, Dutch, Estonian, French, German, Italian, + Lithuanian, Persian, Polish, Portuguese, Russian, Spanish, Swedish, and + Turkish locales + +A number of accessibility features were added in this release: + +* Allow keyboard to toggle menu expansion (#1167) +* Allow keyboard to activate permalink (#1162) +* Show keyboard focus on buttons (#1161) +* Maintain aria-expanded along with .current in menu (#1151) +* Respect tab order for prev/next buttons (#1051) + +Fixes +----- + +* Updated Google analytics integration (#1129) +* Add classifier separation on Sphinx 2+ HTML4 writer (#1192) +* Added missing space char in footer (#1188) +* Fix navigation right padding on level2+ elements (#1068) +* Fix navigation expansion button sizes (#1067) +* Wrap inline literals (#1050) +* Fix aria labels (#1056) +* Don't toggle navigation terminal nodes (#1049) +* Fix ``
`` overflow (#1220)
+* Fix literal/ref style inside ``
`` (#1088)
 
 Other Changes
 -------------
@@ -25,22 +64,24 @@ Other Changes
 * Update npm development dependencies (#1096)
 * Don't require npm to build from source (#1039)
 * Use regular toctree instead of toc for singlehtml builder (#507)
-* Templates: Cleanup Whitespace (#1060)
+* Cleanup whitespace in templates (#1060)
 
-Fixes
------
+.. _release-0.5.2:
 
-* Javascript: Add support for deep toc levels (#1089)
-* Use Proper Sass Syntax (#1069)
-* Nav: Fix right padding on level2+ (#1068)
-* Fix Nav Buttons Size (#1067)
-* Fix: wrap inline literals (#1050)
-* Fix aria label (#1056)
-* Respect tab order for prev/next buttons (#1051)
-* Nav: Don't toggle terminal nodes (#1049)
+0.5.2
+=====
+
+:Date: April 5, 2021
+
+.. note:: This commit will not be in ``master``, but was branched directly off ``0.5.1`` to minimize issues.
+          The next full release will contain all PR's previously merged.
+
+* Depend on docutils < 0.17 (#1113)
+
+.. _release-0.5.1:
 
-v0.5.1
-======
+0.5.1
+=====
 
 :Date: January 4, 2021
 
@@ -69,8 +110,10 @@ Other Changes
 * Make Copyright template match sphinx's basic (#933)
 * Packaging: include ``bin/preinstall.js`` (#1005)
 
-v0.5.0
-======
+.. _release-0.5.0:
+
+0.5.0
+=====
 
 :Date: Jun 17, 2020
 
@@ -79,8 +122,10 @@ Fixes
 
 * Fix bullet list spacing to respect simple/complex list styles
 
-v0.5.0rc2
-=========
+.. _release-0.5.0rc2:
+
+0.5.0rc2
+========
 
 :Date: June 5, 2020
 
@@ -92,8 +137,10 @@ Fixes
 * Fix several margin issues with lists, nested lists, and nested content
 * Add colon back to field lists
 
-v0.5.0rc1
-=========
+.. _release-0.5.0rc1:
+
+0.5.0rc1
+========
 
 :Date: May 6, 2020
 
@@ -111,8 +158,10 @@ Other Changes
 * Moved build system from Grunt and friends to Webpack
 * Remove Modernizr, but keep html5shiv (#724, #525)
 
-v0.4.3
-======
+.. _release-0.4.3:
+
+0.4.3
+=====
 
 :Date: Feb 12, 2019
 
@@ -131,8 +180,10 @@ Fixes
 Other Changes
 --------------
 
-v0.4.2
-======
+.. _release-0.4.2:
+
+0.4.2
+=====
 
 :Date: Oct 5, 2018
 
@@ -151,8 +202,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
 
@@ -169,8 +220,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.
@@ -192,8 +243,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
 -----
@@ -204,8 +255,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
 
@@ -238,40 +289,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
 
@@ -280,8 +331,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
@@ -297,8 +348,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/conf.py b/docs/conf.py
index 8773b5d57..6c4da8c04 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -10,12 +10,14 @@
 sys.path.append(os.path.abspath('./demo/'))
 
 import sphinx_rtd_theme
+from sphinx_rtd_theme import __version__ as theme_version
+from sphinx_rtd_theme import __version_full__ as theme_version_full
 from sphinx.locale import _
 
 project = u'Read the Docs Sphinx Theme'
 slug = re.sub(r'\W+', '-', project.lower())
-version = '0.5.1'
-release = '0.5.1'
+version = theme_version
+release = theme_version_full
 author = u'Dave Snider, Read the Docs, Inc. & contributors'
 copyright = author
 language = 'en'
@@ -41,7 +43,7 @@
 
 intersphinx_mapping = {
     'rtd': ('https://docs.readthedocs.io/en/stable/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/stable/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
 }
 
 html_theme = 'sphinx_rtd_theme'
diff --git a/docs/configuring.rst b/docs/configuring.rst
index d7dcaf36f..7e22c5b0e 100644
--- a/docs/configuring.rst
+++ b/docs/configuring.rst
@@ -13,7 +13,7 @@ For example:
 .. code:: python
 
     html_theme_options = {
-        'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
+        'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
         'analytics_anonymize_ip': False,
         'logo_only': False,
         'display_version': True,
@@ -96,11 +96,13 @@ Miscellaneous options
 
 .. confval:: analytics_id
 
-    If specified, Google Analytics' javascript is included in your pages.
-    Set the value to the ID provided to you by google (like ``UA-XXXXXXX``).
+    If specified, Google Analytics' `gtag.js`_ is included in your pages.
+    Set the value to the ID provided to you by google (like ``UA-XXXXXXX`` or ``G-XXXXXXXXXX``).
 
     :type: string
 
+    .. _gtag.js: https://developers.google.com/gtagjs
+
 .. confval:: analytics_anonymize_ip
 
     Anonymize visitor IP addresses in Google Analytics.
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 5f0245110..9eedb03f6 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -62,6 +62,89 @@ can be used to test built assets:
 .. _Wyrm: http://www.github.com/snide/wyrm/
 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 
+Testing
+=======
+
+QA testing theme changes and pull requests is complex, due to backwards
+compatibility.
+
+The following cases need to be tested with changes to CSS or JavaScript:
+
+* Multiple, modern browsers should be tested. We officially support back
+  to IE11 at the moment
+* Multiple viewport sizes should be tested for changes. We support large,
+  tablet, and mobile viewport sizes
+* We currently support both the Sphinx HTML4 writer and HTML5 writer. This makes
+  for some complex CSS selectors
+* Multiple major versions of Sphinx should be tested. We currently support back
+  to Sphinx version ``1.6``
+
+It's easiest to test combinations of dependency versions using ``tox``:
+
+.. code:: console
+
+    % tox -e py3-sphinx34-html4
+
+If the tests and build are successful, you can view the built documentation at
+the directory noted by Sphinx:
+
+.. code:: console
+
+    build succeeded, 10 warnings.
+
+    The HTML pages are in .tox/py3-sphinx34-html4/tmp/html.
+    ___________________________ summary ___________________________
+      py3-sphinx34-html4: commands succeeded
+      congratulations :)
+
+You can then open up this path with a series of browsers to test.
+
+The best way to spot UI issues is to compare two or more builds. You can build
+multiple ``tox`` environments, and open both up for comparison:
+
+.. code:: console
+
+    % tox -e py3-sphinx34-html4
+    ...
+    % tox -e py3-sphinx34-html5
+    ...
+    % firefox .tox/py3-sphinx34-html4/tmp/html/index.html
+    % firefox .tox/py3-sphinx34-html5/tmp/html/index.html
+
+You can also use a separate ``tox`` environment for building output to compare
+against. All of the ``tox`` environments have an additional postfix, ``-qa``, to
+allow building the same environment twice, without overwriting any files. In
+this test scenario, you would build from a branch or tag before building the
+same ``tox`` environment for the pull request branch you are testing.
+
+For example, to test against the tag ``0.5.2``:
+
+.. code:: console
+
+    % git checkout 0.5.2
+    % tox -e py3-sphinx34-html4-qa
+    ...
+    % git checkout feature/example-pull-request
+    % tox -e py3-sphinx34-html4
+    ...
+    % firefox .tox/py3-sphinx34-html4-qa/tmp/html/index.html
+    % firefox .tox/py3-sphinx34-html4/tmp/html/index.html
+
+Currently, the most important environments to QA are:
+
+.. This list is purposely shorter than what we describe above. If we test all of
+   the cases above, we'll be here all day. Python 3, HTML4/5 writer, and latest
+   minor of each major Sphinx release should give us enough work.
+
+* ``py3-sphinx18-html4``
+* ``py3-sphinx18-html5``
+* ``py3-sphinx24-html4``
+* ``py3-sphinx24-html5``
+* ``py3-sphinx35-html4``
+* ``py3-sphinx35-html5``
+* ``py3-sphinx41-html4``
+* ``py3-sphinx41-html5``
+
 Translations
 ============
 
@@ -92,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 `_ 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,
@@ -114,4 +197,9 @@ To release a new version of the theme, core team will take the following steps:
       $ python setup.py sdist bdist_wheel
       $ twine upload --sign --identity security@readthedocs.org dist/*
 
+#. Finally, open a new pull request updating the development release version to
+   the next patch by running ``bump2version patch``. Open a pull request with
+   this change.
+
 .. _PEP440: https://www.python.org/dev/peps/pep-0440/
+.. _semantic versioning: http://semver.org/
diff --git a/docs/demo/test_py_module/test.py b/docs/demo/test_py_module/test.py
index f47b9840c..812544fb5 100644
--- a/docs/demo/test_py_module/test.py
+++ b/docs/demo/test_py_module/test.py
@@ -65,6 +65,7 @@ def add(self, val1, val2):
         :type val2: int
         :rtype: int
 
+        The parameters of this method are described in the parameter list.
         """
 
         return val1 + val2
@@ -111,3 +112,23 @@ def another_function(self, a, b, **kwargs):
             This is deprecated since 3.0
         """
         return sum(kwargs.values()) / len(kwargs), a + b
+
+
+def add_numbers(a: int, b: int = 0) -> int:
+    """Add two numbers together
+
+    :param a: The first number
+    :param b: The second number
+
+    Here is some more text.
+    """
+    return a + b
+
+
+def subtract_numbers(a: int, b: int = 0) -> int:
+    """Subtract two numbers
+
+    :param a: The first number
+    :param b: The second number
+    """
+    return a - b
diff --git a/docs/development.rst b/docs/development.rst
new file mode 100644
index 000000000..1bf607d55
--- /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/
+
+.. _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
diff --git a/docs/index.rst b/docs/index.rst
index 615fd93e8..28bb8c07f 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 `
+    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 `
+    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 759e73a9c..522b986b3 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,11 +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
-=============
-
-``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 000000000..7e446d909
--- /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
diff --git a/package-lock.json b/package-lock.json
index 38150720e..3cb951fd5 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,6 +1,6 @@
 {
   "name": "sphinx_rtd_theme",
-  "version": "0.5.1",
+  "version": "1.0.1alpha1",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {
@@ -451,13 +451,13 @@
       }
     },
     "assert-plus": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/assert-plus/-/assert-plus-1.0.0.tgz",
       "integrity": "sha1-8S4PPF13sLHN2RRpQuTpbB5N1SU=",
       "dev": true
     },
     "assign-symbols": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/assign-symbols/-/assign-symbols-1.0.0.tgz",
       "integrity": "sha1-WWZ/QfrdTyDMvCu5a41Pf3jsA2c=",
       "dev": true
@@ -514,7 +514,7 @@
       "dev": true
     },
     "balanced-match": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz",
       "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=",
       "dev": true
@@ -535,7 +535,7 @@
       },
       "dependencies": {
         "define-property": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/define-property/-/define-property-1.0.0.tgz",
           "integrity": "sha1-dp66rz9KY6rTr56NMEybvnm/sOY=",
           "dev": true,
@@ -544,7 +544,7 @@
           }
         },
         "is-accessor-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-accessor-descriptor/-/is-accessor-descriptor-1.0.0.tgz",
           "integrity": "sha512-m5hnHTkcVsPfqx3AKlyttIPb7J+XykHvJP2B9bZDjlhLIoEq4XoK64Vg7boZlVWYK6LUY94dYPEE7Lh0ZkZKcQ==",
           "dev": true,
@@ -553,7 +553,7 @@
           }
         },
         "is-data-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-data-descriptor/-/is-data-descriptor-1.0.0.tgz",
           "integrity": "sha512-jbRXy1FmtAoCjQkVmIVYwuuqDFUbaOeDjmed1tOGPrsMhtJA4rD9tkgA0F1qJ3gRFRXcHYVkdeaP50Q5rE/jLQ==",
           "dev": true,
@@ -676,7 +676,7 @@
       }
     },
     "boolbase": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
       "integrity": "sha1-aN/1++YMUes3cl6p4+0xDcwed24=",
       "dev": true
@@ -1270,7 +1270,7 @@
       "dev": true
     },
     "collection-visit": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/collection-visit/-/collection-visit-1.0.0.tgz",
       "integrity": "sha1-S8A3PBZLwykbTTaMgpzxqApZ3KA=",
       "dev": true,
@@ -1408,7 +1408,7 @@
       "dev": true
     },
     "constants-browserify": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/constants-browserify/-/constants-browserify-1.0.0.tgz",
       "integrity": "sha1-wguW2MYXdIqvHBYCF2DNJ/y4y3U=",
       "dev": true
@@ -1917,7 +1917,7 @@
       },
       "dependencies": {
         "is-accessor-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-accessor-descriptor/-/is-accessor-descriptor-1.0.0.tgz",
           "integrity": "sha512-m5hnHTkcVsPfqx3AKlyttIPb7J+XykHvJP2B9bZDjlhLIoEq4XoK64Vg7boZlVWYK6LUY94dYPEE7Lh0ZkZKcQ==",
           "dev": true,
@@ -1926,7 +1926,7 @@
           }
         },
         "is-data-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-data-descriptor/-/is-data-descriptor-1.0.0.tgz",
           "integrity": "sha512-jbRXy1FmtAoCjQkVmIVYwuuqDFUbaOeDjmed1tOGPrsMhtJA4rD9tkgA0F1qJ3gRFRXcHYVkdeaP50Q5rE/jLQ==",
           "dev": true,
@@ -1992,13 +1992,13 @@
       }
     },
     "delayed-stream": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
       "integrity": "sha1-3zrhmayt+31ECqrgsp4icrJOxhk=",
       "dev": true
     },
     "delegates": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/delegates/-/delegates-1.0.0.tgz",
       "integrity": "sha1-hMbhWbgZBP3KWaDvRM2HDTElD5o=",
       "dev": true
@@ -2026,7 +2026,7 @@
       "dev": true
     },
     "detect-file": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/detect-file/-/detect-file-1.0.0.tgz",
       "integrity": "sha1-8NZtA2cqglyxtzvbP+YjEMjlUrc=",
       "dev": true
@@ -2083,7 +2083,7 @@
       }
     },
     "dns-equal": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/dns-equal/-/dns-equal-1.0.0.tgz",
       "integrity": "sha1-s55/HabrCnW6nBcySzR1PEfgZU0=",
       "dev": true
@@ -2417,7 +2417,7 @@
       }
     },
     "execa": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/execa/-/execa-1.0.0.tgz",
       "integrity": "sha512-adbxcyWV46qiHyvSp50TKt05tB4tK3HcmF7/nxfAdhnox83seTDbwnaqKO4sXRy7roHAIFqJP/Rw/AuEbX61LA==",
       "dev": true,
@@ -2586,7 +2586,7 @@
       },
       "dependencies": {
         "define-property": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/define-property/-/define-property-1.0.0.tgz",
           "integrity": "sha1-dp66rz9KY6rTr56NMEybvnm/sOY=",
           "dev": true,
@@ -2604,7 +2604,7 @@
           }
         },
         "is-accessor-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-accessor-descriptor/-/is-accessor-descriptor-1.0.0.tgz",
           "integrity": "sha512-m5hnHTkcVsPfqx3AKlyttIPb7J+XykHvJP2B9bZDjlhLIoEq4XoK64Vg7boZlVWYK6LUY94dYPEE7Lh0ZkZKcQ==",
           "dev": true,
@@ -2613,7 +2613,7 @@
           }
         },
         "is-data-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-data-descriptor/-/is-data-descriptor-1.0.0.tgz",
           "integrity": "sha512-jbRXy1FmtAoCjQkVmIVYwuuqDFUbaOeDjmed1tOGPrsMhtJA4rD9tkgA0F1qJ3gRFRXcHYVkdeaP50Q5rE/jLQ==",
           "dev": true,
@@ -2809,7 +2809,7 @@
       }
     },
     "fresh": {
-      "version": "0.5.2",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz",
       "integrity": "sha1-PYyt2Q2XZWn6g1qx+OSyOhBWBac=",
       "dev": true
@@ -2837,7 +2837,7 @@
       }
     },
     "fs.realpath": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
       "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=",
       "dev": true
@@ -3107,7 +3107,7 @@
       "dev": true
     },
     "has-value": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/has-value/-/has-value-1.0.0.tgz",
       "integrity": "sha1-GLKB2lhbHFxR3vJMkw7SmgvmsXc=",
       "dev": true,
@@ -3118,7 +3118,7 @@
       }
     },
     "has-values": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/has-values/-/has-values-1.0.0.tgz",
       "integrity": "sha1-lbC2P+whRmGab+V/51Yo1aOe/k8=",
       "dev": true,
@@ -3223,13 +3223,13 @@
       }
     },
     "hsl-regex": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/hsl-regex/-/hsl-regex-1.0.0.tgz",
       "integrity": "sha1-1JMwx4ntgZ4nakwNJy3/owsY/m4=",
       "dev": true
     },
     "hsla-regex": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/hsla-regex/-/hsla-regex-1.0.0.tgz",
       "integrity": "sha1-wc56MWjIxmFAM6S194d/OyJfnDg=",
       "dev": true
@@ -3320,7 +3320,7 @@
       }
     },
     "https-browserify": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/https-browserify/-/https-browserify-1.0.0.tgz",
       "integrity": "sha1-7AbBDgo0wPL68Zn3/X/Hj//QPHM=",
       "dev": true
@@ -3650,7 +3650,7 @@
       "dev": true
     },
     "is-fullwidth-code-point": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-1.0.0.tgz",
       "integrity": "sha1-754xOG8DGn8NZDr4L95QxFfvAMs=",
       "dev": true,
@@ -3791,7 +3791,7 @@
       }
     },
     "is-typedarray": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/is-typedarray/-/is-typedarray-1.0.0.tgz",
       "integrity": "sha1-5HnICFjfDBsR3dppQPlgEfzaSpo=",
       "dev": true
@@ -3815,7 +3815,7 @@
       "dev": true
     },
     "isarray": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
       "integrity": "sha1-u5NdSFgsuhaMBoNJV6VKPgcSTxE=",
       "dev": true
@@ -4068,7 +4068,7 @@
       "dev": true
     },
     "map-visit": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/map-visit/-/map-visit-1.0.0.tgz",
       "integrity": "sha1-7Nyo8TFE5mDxtb1B8S80edmN+48=",
       "dev": true,
@@ -4756,7 +4756,7 @@
       }
     },
     "p-finally": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/p-finally/-/p-finally-1.0.0.tgz",
       "integrity": "sha1-P7z7FbiZpEEjs0ttzBi3JDNqLK4=",
       "dev": true
@@ -4840,7 +4840,7 @@
       }
     },
     "parse-passwd": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/parse-passwd/-/parse-passwd-1.0.0.tgz",
       "integrity": "sha1-bVuTSkVpk7I9N/QKOC1vFmao5cY=",
       "dev": true
@@ -5868,7 +5868,7 @@
       }
     },
     "redent": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/redent/-/redent-1.0.0.tgz",
       "integrity": "sha1-z5Fqsf1fHxbfsggi3W7H9zDCr94=",
       "dev": true,
@@ -5959,7 +5959,7 @@
       "dev": true
     },
     "requires-port": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
       "integrity": "sha1-kl0mAdOaxIXgkc8NpcbmlNw9yv8=",
       "dev": true
@@ -5993,7 +5993,7 @@
       },
       "dependencies": {
         "global-modules": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/global-modules/-/global-modules-1.0.0.tgz",
           "integrity": "sha512-sKzpEkf11GpOFuw0Zzjzmt4B4UZwjOcG757PPvrfhxcLFbq0wpsgpOqxpxtxFiCG4DtG93M6XRVbF2oGdev7bg==",
           "dev": true,
@@ -6036,7 +6036,7 @@
       "dev": true
     },
     "rgba-regex": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/rgba-regex/-/rgba-regex-1.0.0.tgz",
       "integrity": "sha1-QzdOLiyglosO8VI0YLfXMP8i7rM=",
       "dev": true
@@ -6142,7 +6142,7 @@
       "dev": true
     },
     "schema-utils": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/schema-utils/-/schema-utils-1.0.0.tgz",
       "integrity": "sha512-i27Mic4KovM/lnGsy8whRCHhc7VicJajAjTrYg11K9zfZXnYIt4k5F+kZkwjnrhKzLic/HLU4j11mjsz2G/75g==",
       "dev": true,
@@ -6344,7 +6344,7 @@
       }
     },
     "shebang-regex": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-1.0.0.tgz",
       "integrity": "sha1-2kL0l0DAtC2yypcoVxyxkMmO/qM=",
       "dev": true
@@ -6373,7 +6373,7 @@
       }
     },
     "slash": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/slash/-/slash-1.0.0.tgz",
       "integrity": "sha1-xB8vbDn8FtHNF61LXYlhFK5HDVU=",
       "dev": true
@@ -6432,7 +6432,7 @@
       },
       "dependencies": {
         "define-property": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/define-property/-/define-property-1.0.0.tgz",
           "integrity": "sha1-dp66rz9KY6rTr56NMEybvnm/sOY=",
           "dev": true,
@@ -6441,7 +6441,7 @@
           }
         },
         "is-accessor-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-accessor-descriptor/-/is-accessor-descriptor-1.0.0.tgz",
           "integrity": "sha512-m5hnHTkcVsPfqx3AKlyttIPb7J+XykHvJP2B9bZDjlhLIoEq4XoK64Vg7boZlVWYK6LUY94dYPEE7Lh0ZkZKcQ==",
           "dev": true,
@@ -6450,7 +6450,7 @@
           }
         },
         "is-data-descriptor": {
-          "version": "1.0.0",
+          "version": "1.0.1alpha1",
           "resolved": "https://registry.npmjs.org/is-data-descriptor/-/is-data-descriptor-1.0.0.tgz",
           "integrity": "sha512-jbRXy1FmtAoCjQkVmIVYwuuqDFUbaOeDjmed1tOGPrsMhtJA4rD9tkgA0F1qJ3gRFRXcHYVkdeaP50Q5rE/jLQ==",
           "dev": true,
@@ -6893,7 +6893,7 @@
       }
     },
     "strip-eof": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/strip-eof/-/strip-eof-1.0.0.tgz",
       "integrity": "sha1-u0P/VZim6wXYm1n80SnJgzE2Br8=",
       "dev": true
@@ -7140,7 +7140,7 @@
       }
     },
     "toidentifier": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.0.tgz",
       "integrity": "sha512-yaOH/Pk/VEhBWWTlhI+qXxDFXlejDGcQipMlyxda9nthulaxLZUNcUqFxokp0vcYnvteJln5FNQDRrxj3YcbVw==",
       "dev": true
@@ -7156,7 +7156,7 @@
       }
     },
     "trim-newlines": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/trim-newlines/-/trim-newlines-1.0.0.tgz",
       "integrity": "sha1-WIeWa7WCpFA6QetST301ARgVphM=",
       "dev": true
@@ -7214,7 +7214,7 @@
       "dev": true
     },
     "unbox-primitive": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.0.0.tgz",
       "integrity": "sha512-P/51NX+JXyxK/aigg1/ZgyccdAxm5K1+n8+tvqSntjOivPt19gvm1VC49RWYetsiub8WViUchdxl/KWHHB0kzA==",
       "dev": true,
@@ -7268,7 +7268,7 @@
       }
     },
     "unpipe": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
       "integrity": "sha1-sr9O6FFKrmFltIF4KdIbLvSZBOw=",
       "dev": true
@@ -7280,7 +7280,7 @@
       "dev": true
     },
     "unset-value": {
-      "version": "1.0.0",
+      "version": "1.0.1alpha1",
       "resolved": "https://registry.npmjs.org/unset-value/-/unset-value-1.0.0.tgz",
       "integrity": "sha1-g3aHP30jNRef+x5vw6jtDfyKtVk=",
       "dev": true,
diff --git a/package.json b/package.json
index d7bfff2a2..b755632de 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "sphinx_rtd_theme",
   "main": "js/theme.js",
-  "version": "0.5.1",
+  "version": "1.0.1alpha1",
   "scripts": {
     "dev": "webpack-dev-server --open --config webpack.dev.js",
     "build": "webpack --config webpack.prod.js",
diff --git a/setup.cfg b/setup.cfg
index fcbf17d68..5e60f7829 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,5 +1,63 @@
+[metadata]
+name = sphinx_rtd_theme
+url = https://github.com/readthedocs/sphinx_rtd_theme
+license = MIT
+author = Dave Snider, Read the Docs, Inc. & contributors
+author_email = dev@readthedocs.org
+description = Read the Docs theme for Sphinx
+long_description = file: README.rst
+project_urls =
+  Homepage = https://sphinx-rtd-theme.readthedocs.io/
+  Source Code = https://github.com/readthedocs/sphinx_rtd_theme
+  Issue Tracker = https://github.com/readthedocs/sphinx_rtd_theme/issues
+classifiers =
+  Framework :: Sphinx
+  Framework :: Sphinx :: Theme
+  Development Status :: 5 - Production/Stable
+  License :: OSI Approved :: MIT License
+  Environment :: Console
+  Environment :: Web Environment
+  Intended Audience :: Developers
+  Programming Language :: Python :: 2.7
+  Programming Language :: Python :: 3
+  Programming Language :: Python :: 3.6
+  Programming Language :: Python :: 3.7
+  Programming Language :: Python :: 3.8
+  Programming Language :: Python :: 3.9
+  Operating System :: OS Independent
+  Topic :: Documentation
+  Topic :: Software Development :: Documentation
+[options]
+include_package_data = True
+zip_safe = False
+packages = sphinx_rtd_theme
+install_requires =
+  sphinx >=1.6
+  docutils <0.18
+  Jinja2 <3.1
+tests_require =
+  pytest
+
+[options.extras_require]
+dev =
+  transifex-client
+  sphinxcontrib-httpdomain
+  bump2version
+
+[options.entry_points]
+sphinx.html_themes =
+  sphinx_rtd_theme = sphinx_rtd_theme
+
+[options.package_data]
+sphinx_rtd_theme =
+  theme.conf
+  *.html
+  static/css/*.css
+  static/css/fonts/*.*
+  static/js/*.js
+
 [bumpversion]
-current_version = 0.5.1
+current_version = 1.0.1alpha1
 commit = false
 tag = false
 parse = (?P\d+)\.(?P\d+)\.(?P\d+)((?P[a-z]+)(?P\d+))?
@@ -53,4 +111,6 @@ replace = "version": "{new_version}",
 search = "version": "{current_version}",
 replace = "version": "{new_version}",
 
-[bumpversion:file:docs/conf.py]
+[bumpversion:file:docs/changelog.rst]
+search = .. |development_version| replace:: {current_version}
+replace = .. |development_version| replace:: {new_version}
diff --git a/setup.py b/setup.py
index 362c81398..5a9c1879a 100644
--- a/setup.py
+++ b/setup.py
@@ -86,70 +86,11 @@ def run(self):
 
 
 setup(
-    name='sphinx_rtd_theme',
-    version='0.5.1',
-    url='https://github.com/readthedocs/sphinx_rtd_theme',
-    license='MIT',
-    author='Dave Snider, Read the Docs, Inc. & contributors',
-    author_email='dev@readthedocs.org',
-    description='Read the Docs theme for Sphinx',
-    long_description=open('README.rst', encoding='utf-8').read(),
+    version='1.0.1alpha1',
     cmdclass={
         'update_translations': UpdateTranslationsCommand,
         'transifex': TransifexCommand,
         'build_assets': WebpackBuildCommand,
         'watch': WebpackDevelopCommand,
     },
-    zip_safe=False,
-    packages=['sphinx_rtd_theme'],
-    package_data={'sphinx_rtd_theme': [
-        'theme.conf',
-        '*.html',
-        'static/css/*.css',
-        'static/css/fonts/*.*'
-        'static/js/*.js',
-    ]},
-    include_package_data=True,
-    # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
-    entry_points = {
-        'sphinx.html_themes': [
-            'sphinx_rtd_theme = sphinx_rtd_theme',
-        ]
-    },
-    install_requires=[
-        'sphinx>=1.6'
-    ],
-    tests_require=[
-        'pytest',
-    ],
-    extras_require={
-        'dev': [
-            'transifex-client',
-            'sphinxcontrib-httpdomain',
-            'bump2version',
-        ],
-    },
-    classifiers=[
-        'Framework :: Sphinx',
-        'Framework :: Sphinx :: Theme',
-        'Development Status :: 5 - Production/Stable',
-        'License :: OSI Approved :: MIT License',
-        'Environment :: Console',
-        'Environment :: Web Environment',
-        'Intended Audience :: Developers',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
-        'Programming Language :: Python :: 3.8',
-        'Programming Language :: Python :: 3.9',
-        'Operating System :: OS Independent',
-        'Topic :: Documentation',
-        'Topic :: Software Development :: Documentation',
-    ],
-    project_urls={
-        'Homepage': 'https://sphinx-rtd-theme.readthedocs.io/',
-        'Source Code': 'https://github.com/readthedocs/sphinx_rtd_theme',
-        'Issue Tracker': 'https://github.com/readthedocs/sphinx_rtd_theme/issues',
-    },
 )
diff --git a/sphinx_rtd_theme/__init__.py b/sphinx_rtd_theme/__init__.py
index 2bc649972..f31909865 100644
--- a/sphinx_rtd_theme/__init__.py
+++ b/sphinx_rtd_theme/__init__.py
@@ -12,7 +12,7 @@
 from sphinx.util.logging import getLogger
 
 
-__version__ = '0.5.1'
+__version__ = '1.0.1alpha1'
 __version_full__ = __version__
 
 logger = getLogger(__name__)
@@ -31,7 +31,6 @@ def config_initiated(app, config):
             _('The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead.')
         )
 
-
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
     if python_version[0] < 3:
@@ -55,4 +54,10 @@ def setup(app):
         app.add_message_catalog('sphinx', rtd_locale_path)
         app.connect('config-inited', config_initiated)
 
+    # sphinx emits the permalink icon for headers, so choose one more in keeping with our theme
+    if sphinx_version >= (3, 5, 0):
+        app.config.html_permalinks_icon = "\uf0c1"
+    else:
+        app.config.html_add_permalinks = "\uf0c1"
+
     return {'parallel_read_safe': True, 'parallel_write_safe': True}
diff --git a/sphinx_rtd_theme/breadcrumbs.html b/sphinx_rtd_theme/breadcrumbs.html
index 722e266be..005b2ecd6 100644
--- a/sphinx_rtd_theme/breadcrumbs.html
+++ b/sphinx_rtd_theme/breadcrumbs.html
@@ -18,7 +18,8 @@
 
 {%- set display_vcs_links = display_vcs_links if display_vcs_links is defined else True %}
 
-

+{#- Translators: This is an ARIA section label for page links, including previous/next page link and links to GitHub/GitLab/etc. -#}
+

   
    
     {%- block breadcrumbs %}
       
  •  »
    • 
@@ -62,7 +63,8 @@
   

 
   {%- if (theme_prev_next_buttons_location == 'top' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
-