IntenseWebs/sphinx_rtd_theme
3
0
Fork 0
mirror of https://github.com/readthedocs/sphinx_rtd_theme.git synced 2025-02-25 18:55:21 -06:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Benjamin Balder Bach
2022-11-09 13:40:16 +01:00
committed by GitHub
parent bef1649055
commit 25d6fe3605
5 changed files with 45 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/changelog.rst
View File

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

2
docs/conf.py
View File

@@ -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),
}

6
docs/contributing.rst
View File

@@ -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

18
docs/development.rst
View File

@@ -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
~~~~~

35
docs/installing.rst
View File

@@ -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