Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 14 commits into from
Nov 9, 2022
Merged

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

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
6cbd3a2
Docs: Clean up several broken cross-references
benjaoming Oct 20, 2022
c75eef1
Adds a section about upgrading the theme and add navigation structure…
benjaoming Oct 20, 2022
d4d0286
Add a reference from Changelog to "How to upgrade"
benjaoming Oct 20, 2022
99febd2
Also don't import sphinx_rtd_theme in the theme's own docs/conf.py
benjaoming Oct 20, 2022
e78e9b2
Remove trailing linebreaks
benjaoming Oct 25, 2022
e1de5ec
Update docs/installing.rst
benjaoming Oct 25, 2022
d75b5ad
Apply suggestions from code review
benjaoming Oct 25, 2022
691d577
Update docs/installing.rst
benjaoming Oct 26, 2022
b0b22fd
Replace guidance with reference to Reproducible Builds
benjaoming Oct 26, 2022
2efb78f
Merge branch 'upgrade-instructions' of github.com:benjaoming/sphinx_r…
benjaoming Oct 26, 2022
9c82023
Build link into sentence
benjaoming Oct 26, 2022
f7824f8
Merge branch 'master' into upgrade-instructions
benjaoming Nov 8, 2022
0bae8ec
Update the tip about using build logs and the need to pin the theme f…
benjaoming Nov 9, 2022
855dd48
Remove tip box for Read the Docs users re: @agjohnson's request
benjaoming Nov 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
Changelog
*********

.. seealso:: :ref:`howto_upgrade`

Development version (|development_version|)
===========================================

Expand Down
2 changes: 1 addition & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 _
Expand Down Expand Up @@ -43,6 +42,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),
}

Expand Down
6 changes: 3 additions & 3 deletions docs/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down Expand Up @@ -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
======================
Expand Down Expand Up @@ -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
Expand Down
18 changes: 9 additions & 9 deletions docs/development.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
~~~~~
Expand Down Expand Up @@ -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
~~~~~
Expand Down
44 changes: 39 additions & 5 deletions docs/installing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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',
Expand All @@ -27,21 +28,54 @@ 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
--------------

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

.. 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
Expand Down