mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
25d6fe3605
* 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>
79 lines
2.5 KiB
ReStructuredText
79 lines
2.5 KiB
ReStructuredText
Installation
|
|
============
|
|
|
|
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 Sphinx project's ``conf.py`` file, add ``sphinx_rtd_theme`` to the list of enabled extensions and as the active theme:
|
|
|
|
.. code:: python
|
|
|
|
extensions = [
|
|
...
|
|
'sphinx_rtd_theme',
|
|
]
|
|
|
|
html_theme = "sphinx_rtd_theme"
|
|
|
|
.. seealso::
|
|
:ref:`supported-browsers`
|
|
Officially supported and tested browser/operating system combinations
|
|
|
|
: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:`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
|
|
``conf.py`` file:
|
|
|
|
.. code:: python
|
|
|
|
html_theme = "sphinx_rtd_theme"
|
|
html_theme_path = ["_themes", ]
|