Docs: Add upgrade instructions and simplify conf.py (#1365)

* Docs: Clean up several broken cross-references

* Adds a section about upgrading the theme and add navigation structure to installation guide

* Add a reference from Changelog to "How to upgrade"

* Also don't import sphinx_rtd_theme in the theme's own docs/conf.py

* Remove trailing linebreaks

* Update docs/installing.rst

Co-authored-by: Anthony <aj@ohess.org>

* Apply suggestions from code review

Co-authored-by: Anthony <aj@ohess.org>

* Update docs/installing.rst

* Replace guidance with reference to Reproducible Builds

* Build link into sentence

* Update the tip about using build logs and the need to pin the theme for older projects

* Remove tip box for Read the Docs users re: @agjohnson's request

Co-authored-by: Anthony <aj@ohess.org>

docs/changelog.rst

@@ -2,6 +2,8 @@
 Changelog
 *********
 
+.. seealso:: :ref:`howto_upgrade`
+
 Development version (|development_version|)
 ===========================================
 

docs/conf.py

@@ -9,7 +9,6 @@
 sys.path.insert(0, os.path.abspath('..'))
 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 _
@@ -49,6 +48,7 @@
 
 intersphinx_mapping = {
     'rtd': ('https://docs.readthedocs.io/en/stable/', None),
+    'rtd-dev': ('https://dev.readthedocs.io/en/stable/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
 }
 

docs/contributing.rst

@@ -3,7 +3,7 @@ Contributing
 ************
 
 This project follows the Read the Docs :doc:`code of conduct
-<rtd:code-of-conduct>`. If you are not familiar with our code of conduct policy,
+<rtd-dev:code-of-conduct>`. If you are not familiar with our code of conduct policy,
 take a minute to read the policy before starting with your first contribution.
 
 .. tip::
@@ -66,7 +66,7 @@ can be used to test built assets:
 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 
 
-_dockerized-build::
+.. _dockerized-build:
 
 Dockerized development
 ======================
@@ -184,7 +184,7 @@ Translations
 Translations are managed using `Transifex`_. You can join any of the existing
 language teams or request a new language is added to the project. For more
 information on our translation standards, see our docs on
-:doc:`rtd:development/i18n`
+:doc:`rtd-dev:i18n`
 
 Periodically, core team should update the translation files outside our normal
 releases. Someone from the core team, with write access to Transifex, should run

docs/development.rst

@@ -42,7 +42,7 @@ Internet Explorer (any OS, versions <=10)
 
 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.
+    Support will be removed in the :ref:`roadmap-release-2.0.0` release.
 
 Opera (any OS, any version)
     **Community support only.** We do not receive enough traffic with this
@@ -94,15 +94,15 @@ version:
 
 .. _semantic versioning: http://semver.org/
 
-.. _release-1.0.0:
+.. _roadmap-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
+:ref:`release-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
@@ -120,25 +120,25 @@ Direct installation is deprecated
     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`:.
+    Built assets are tentatively planned to be removed in version :ref:`roadmap-release-3.0.0`:.
 
 HTML4 support is deprecated
-    Support for the Sphinx HTML4 writer will be removed in the :ref:`2.0.0`
+    Support for the Sphinx HTML4 writer will be removed in the :ref:`roadmap-release-2.0.0`
     release.
 
-.. _release-1.1.0:
+.. _roadmap-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
+We aim to follow up release :ref:`release-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:
+.. _roadmap-release-2.0.0:
 
 2.0.0
 ~~~~~
@@ -166,7 +166,7 @@ HTML4 support will be removed
     support and should no longer be required to use a modern combination of this
     theme and Sphinx.
 
-.. _release-3.0.0:
+.. _roadmap-release-3.0.0:
 
 3.0.0
 ~~~~~

docs/installing.rst

@@ -1,18 +1,19 @@
 Installation
 ============
 
-Install the package (or add it to your ``requirements.txt`` file):
+How to install and use the theme
+--------------------------------
+
+Install the ``sphinx_rtd_theme`` package (or add it to your ``requirements.txt`` file):
 
 .. code:: console
 
     $ pip install sphinx_rtd_theme
 
-In your ``conf.py`` file:
+In your Sphinx project's ``conf.py`` file, add ``sphinx_rtd_theme`` to the list of enabled extensions and as the active theme:
 
 .. code:: python
 
-    import sphinx_rtd_theme
-
     extensions = [
         ...
         'sphinx_rtd_theme',
@@ -27,21 +28,45 @@ In your ``conf.py`` file:
     :ref:`supported-dependencies`
         Officially Supported versions of Python, Sphinx, and other dependencies.
 
+
 .. note::
 
    Adding this theme as an extension is what enables localization of theme
    strings in your translated output. If these strings are not translated in
    your output, either we lack the localized strings for your locale, or you
    are using an old version of the theme.
 
+   ..
+      comment about this note: it's possibly not necessary to add the theme as an extension.
+      Rather, this is an issue caused by setting html_theme_path.
+      See: https://github.com/readthedocs/readthedocs.org/pull/9654
+
+
+.. _howto_upgrade:
+
+How to upgrade
+--------------
+
+Adding ``sphinx-rtd-theme`` to your project's dependencies will make pip install the latest compatible version of the theme.
+
+If you want to test a **pre-release**, you need to be explicit about the version you specify.
+Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1.1.0b3`` to test a pre-release.
+
+.. tip::
+    We recommend that you pin the version of Sphinx that your project is built with.
+    We won't release sphinx-rtd-theme without marking its compatibility with Sphinx. So if you do not pin ``sphinx-rtd-theme`` itself, you will always get the *latest compatible* release.
+
+    More information is available in Read the Docs' documentation on :doc:`rtd:guides/reproducible-builds`.
+
+
 Via Git or Download
 -------------------
 
 .. warning::
 
    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`.
+   release :ref:`roadmap-release-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