From 6cbd3a20c3c3aa71d21b04d55af1cd7c28f5728b Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 20 Oct 2022 18:03:56 +0200 Subject: [PATCH 01/12] Docs: Clean up several broken cross-references --- docs/conf.py | 1 + docs/contributing.rst | 6 +++--- docs/development.rst | 18 +++++++++--------- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 6c4da8c04..881f0ae2f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,6 +43,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), } diff --git a/docs/contributing.rst b/docs/contributing.rst index 2ef56dbbc..2416778e7 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -3,7 +3,7 @@ Contributing ************ This project follows the Read the Docs :doc:`code of conduct -`. If you are not familiar with our code of conduct policy, +`. 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 diff --git a/docs/development.rst b/docs/development.rst index 1bf607d55..c11cf159e 100644 --- a/docs/development.rst +++ b/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,7 +94,7 @@ version: .. _semantic versioning: http://semver.org/ -.. _release-1.0.0: +.. _roadmap-release-1.0.0: 1.0.0 ~~~~~ @@ -102,7 +102,7 @@ version: :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 ~~~~~ From c75eef146e6d505dfdd7477078a4f14022242cb6 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 20 Oct 2022 18:04:25 +0200 Subject: [PATCH 02/12] Adds a section about upgrading the theme and add navigation structure to installation guide --- docs/installing.rst | 48 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index 522b986b3..ac76faa14 100644 --- a/docs/installing.rst +++ b/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,6 +28,7 @@ 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 @@ -34,6 +36,38 @@ In your ``conf.py`` file: 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 + + +.. _rtd_upgrade: + +How to upgrade +-------------- + +.. tip:: + **Read the Docs users:** To know which version of ``sphinx-rtd-theme`` you are running, you can always check your latest build outputs. One or more steps in the documentation build will install python packages, one of which is ``sphinx-rtd-theme``. + +Adding ``sphinx-rtd-theme`` to your project's ``requirements.txt`` 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 in ``requirements.txt``. +Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1.1.0b3`` to test a pre-release. + +.. tip:: + We always recommend that you pin the version of Sphinx that your project is built with. + We'll make sure not to release sphinx-rtd-theme that installs together with a Sphinx theme that it is incompatible with. + + It can never be guaranteed that sphinx-rtd-theme is compatible with everything in your project. + If your project is complex or needs reproducible documentation builds, you should pin or put an upper bound on ``sphinx-rtd-theme``. + For instance, you could add this to ``requirements.txt``:: + + # Ensure that we do not automatically include changes from the next major series + sphinx-rtd-theme>=1,<2 + + + Via Git or Download ------------------- @@ -41,7 +75,7 @@ Via Git or Download 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 @@ -51,3 +85,7 @@ Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into you html_theme = "sphinx_rtd_theme" html_theme_path = ["_themes", ] + + + + From d4d02869f58e4d6a0cbe6de46a0d8e9b331dc828 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 20 Oct 2022 18:20:21 +0200 Subject: [PATCH 03/12] Add a reference from Changelog to "How to upgrade" --- docs/changelog.rst | 2 ++ docs/installing.rst | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index abd307189..f82055026 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -2,6 +2,8 @@ Changelog ********* +.. seealso:: :ref:`howto_upgrade` + Development version (|development_version|) =========================================== diff --git a/docs/installing.rst b/docs/installing.rst index ac76faa14..661744373 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -42,7 +42,7 @@ In your Sphinx project's ``conf.py`` file, add ``sphinx_rtd_theme`` to the list See: https://github.com/readthedocs/readthedocs.org/pull/9654 -.. _rtd_upgrade: +.. _howto_upgrade: How to upgrade -------------- From 99febd2d9ef2d65cff673b1a15b10f150124726d Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 20 Oct 2022 18:53:55 +0200 Subject: [PATCH 04/12] Also don't import sphinx_rtd_theme in the theme's own docs/conf.py --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 881f0ae2f..a3f2208d8 100644 --- a/docs/conf.py +++ b/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 _ From e78e9b2a8f43c7fcef96b97fc66246fea02141b4 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 25 Oct 2022 18:39:35 +0200 Subject: [PATCH 05/12] Remove trailing linebreaks --- docs/installing.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index 661744373..06aec13a2 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -85,7 +85,3 @@ Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into you html_theme = "sphinx_rtd_theme" html_theme_path = ["_themes", ] - - - - From e1de5ec8b4d24eb58f8c6c4cc6a134a09c344bc2 Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Tue, 25 Oct 2022 21:58:31 +0200 Subject: [PATCH 06/12] Update docs/installing.rst Co-authored-by: Anthony --- docs/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installing.rst b/docs/installing.rst index 06aec13a2..d4cbb33a4 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -50,7 +50,7 @@ How to upgrade .. tip:: **Read the Docs users:** To know which version of ``sphinx-rtd-theme`` you are running, you can always check your latest build outputs. One or more steps in the documentation build will install python packages, one of which is ``sphinx-rtd-theme``. -Adding ``sphinx-rtd-theme`` to your project's ``requirements.txt`` will make pip install the latest compatible version of the theme. +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 in ``requirements.txt``. Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1.1.0b3`` to test a pre-release. From d75b5ad4e6c047e9bebdc15e1dd262e9b0b26c02 Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Tue, 25 Oct 2022 22:00:32 +0200 Subject: [PATCH 07/12] Apply suggestions from code review Co-authored-by: Anthony --- docs/installing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index d4cbb33a4..f10b37fd3 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -52,11 +52,11 @@ 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 in ``requirements.txt``. +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 always recommend that you pin the version of Sphinx that your project is built with. + We always recommend that you pin the exact version of Sphinx that your project is built with. We'll make sure not to release sphinx-rtd-theme that installs together with a Sphinx theme that it is incompatible with. It can never be guaranteed that sphinx-rtd-theme is compatible with everything in your project. From 691d57743d88cc7d0955503654d6e8a542fab5fb Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Wed, 26 Oct 2022 08:57:49 +0200 Subject: [PATCH 08/12] Update docs/installing.rst --- docs/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installing.rst b/docs/installing.rst index f10b37fd3..0b8273f90 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -57,7 +57,7 @@ Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1. .. tip:: We always recommend that you pin the exact version of Sphinx that your project is built with. - We'll make sure not to release sphinx-rtd-theme that installs together with a Sphinx theme that it is incompatible 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. It can never be guaranteed that sphinx-rtd-theme is compatible with everything in your project. If your project is complex or needs reproducible documentation builds, you should pin or put an upper bound on ``sphinx-rtd-theme``. From b0b22fdeb5576ff17275693b46fe62b948294291 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 26 Oct 2022 21:58:09 +0200 Subject: [PATCH 09/12] Replace guidance with reference to Reproducible Builds --- docs/installing.rst | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index 06aec13a2..75feeb808 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -47,24 +47,19 @@ In your Sphinx project's ``conf.py`` file, add ``sphinx_rtd_theme`` to the list How to upgrade -------------- -.. tip:: - **Read the Docs users:** To know which version of ``sphinx-rtd-theme`` you are running, you can always check your latest build outputs. One or more steps in the documentation build will install python packages, one of which is ``sphinx-rtd-theme``. - Adding ``sphinx-rtd-theme`` to your project's ``requirements.txt`` 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 in ``requirements.txt``. Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1.1.0b3`` to test a pre-release. +.. tip:: + **Read the Docs users:** To know which version of ``sphinx-rtd-theme`` you are running, you can always check your latest build outputs. One or more steps in the documentation build will install python packages, one of which is ``sphinx-rtd-theme``. + .. tip:: - We always recommend that you pin the version of Sphinx that your project is built with. + We recommend that you pin the version of Sphinx that your project is built with. We'll make sure not to release sphinx-rtd-theme that installs together with a Sphinx theme that it is incompatible with. - It can never be guaranteed that sphinx-rtd-theme is compatible with everything in your project. - If your project is complex or needs reproducible documentation builds, you should pin or put an upper bound on ``sphinx-rtd-theme``. - For instance, you could add this to ``requirements.txt``:: - - # Ensure that we do not automatically include changes from the next major series - sphinx-rtd-theme>=1,<2 + More information is available in Read the Docs' documentation: :doc:`rtd:guides/reproducible-builds` From 9c8202355fb0ed91458921607b806a8455d790b8 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 26 Oct 2022 22:00:29 +0200 Subject: [PATCH 10/12] Build link into sentence --- docs/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installing.rst b/docs/installing.rst index 50c26926e..ce7704fd7 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -59,7 +59,7 @@ Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1. 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: :doc:`rtd:guides/reproducible-builds` + More information is available in Read the Docs' documentation on :doc:`rtd:guides/reproducible-builds`. From 0bae8ec26aa434b131018e53c183d0edd69628ac Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 9 Nov 2022 01:37:08 +0100 Subject: [PATCH 11/12] Update the tip about using build logs and the need to pin the theme for older projects --- docs/installing.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index ce7704fd7..e7e96a98a 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -52,15 +52,17 @@ Adding ``sphinx-rtd-theme`` to your project's dependencies will make pip install 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:: - **Read the Docs users:** To know which version of ``sphinx-rtd-theme`` you are running, you can always check your latest build outputs. One or more steps in the documentation build will install python packages, one of which is ``sphinx-rtd-theme``. - .. 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`. +.. tip:: + **Read the Docs users:** If you are upgrading a project created before October 20, 2020 (January 21, 2021 for Read the Docs for Business), it's a requirement to specify the version of ``sphinx-rtd-theme``. Otherwise, ``sphinx-rtd-theme`` is pinned to a lower version to address legacy issues. + More information is available in Read the Docs' documentation on :doc:`rtd:build-default-versions`. + We recommend checking your build logs to verify which version of ``sphinx-rtd-theme`` you are running. + Via Git or Download From 855dd4893e1345073d133b5f0aae860ce1c9706c Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 9 Nov 2022 13:29:45 +0100 Subject: [PATCH 12/12] Remove tip box for Read the Docs users re: @agjohnson's request --- docs/installing.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index e7e96a98a..d9a5d00f9 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -58,12 +58,6 @@ Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1. More information is available in Read the Docs' documentation on :doc:`rtd:guides/reproducible-builds`. -.. tip:: - **Read the Docs users:** If you are upgrading a project created before October 20, 2020 (January 21, 2021 for Read the Docs for Business), it's a requirement to specify the version of ``sphinx-rtd-theme``. Otherwise, ``sphinx-rtd-theme`` is pinned to a lower version to address legacy issues. - More information is available in Read the Docs' documentation on :doc:`rtd:build-default-versions`. - We recommend checking your build logs to verify which version of ``sphinx-rtd-theme`` you are running. - - Via Git or Download -------------------