diff options
| -rw-r--r-- | docs/changelog.rst | 2 | ||||
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/contributing.rst | 6 | ||||
| -rw-r--r-- | docs/development.rst | 18 | ||||
| -rw-r--r-- | docs/installing.rst | 35 |
5 files changed, 45 insertions, 18 deletions
diff --git a/docs/changelog.rst b/docs/changelog.rst index b7972fd..fd6302b 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/conf.py b/docs/conf.py index 2973027..8917692 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,7 +9,6 @@ import re 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 @@ else: 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 5a4be56..950c971 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 -<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 diff --git a/docs/development.rst b/docs/development.rst index 1bf607d..c11cf15 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 ~~~~~ diff --git a/docs/installing.rst b/docs/installing.rst index 522b986..d9a5d00 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,29 @@ 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 + + +.. _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 ------------------- @@ -41,7 +66,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 |