mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
doc: Add "theming" to usage guide
This one is a little unusual. The current theming doc mixes user-focused documentation with developer-focused documentation. This is confusing and unnecessary. Resolve the issue by splitting the doc in two. The user-focused docs are moved to the advanced section of the usage guide, while the developer docs remain where they are, pending the addition of a developer guide. Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 39 KiB |
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 56 KiB |
|
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 39 KiB |
|
Before Width: | Height: | Size: 73 KiB After Width: | Height: | Size: 73 KiB |
|
Before Width: | Height: | Size: 71 KiB After Width: | Height: | Size: 71 KiB |
|
Before Width: | Height: | Size: 82 KiB After Width: | Height: | Size: 82 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 100 KiB After Width: | Height: | Size: 100 KiB |
|
Before Width: | Height: | Size: 86 KiB After Width: | Height: | Size: 86 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 82 KiB After Width: | Height: | Size: 82 KiB |
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 90 KiB |
|
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 42 KiB |
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 27 KiB After Width: | Height: | Size: 27 KiB |
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 30 KiB |
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
@@ -14,6 +14,7 @@ Sphinx documentation contents
|
||||
usage/configuration
|
||||
usage/builders/index
|
||||
usage/extensions/index
|
||||
usage/theming
|
||||
usage/advanced/intl
|
||||
usage/advanced/setuptools
|
||||
usage/advanced/websupport/index
|
||||
|
||||
@@ -20,7 +20,7 @@ How do I...
|
||||
the :rst:dir:`toctree` directive where you want to start numbering.
|
||||
|
||||
... customize the look of the built HTML files?
|
||||
Use themes, see :doc:`theming`.
|
||||
Use themes, see :doc:`/usage/theming`.
|
||||
|
||||
... add global substitutions or includes?
|
||||
Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.
|
||||
|
||||
312
doc/theming.rst
312
doc/theming.rst
@@ -5,6 +5,12 @@ HTML theming support
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
.. note::
|
||||
|
||||
This document provides information about creating your own theme. If you
|
||||
simply wish to use a pre-existing HTML themes, refer to
|
||||
:doc:`/usage/theming`.
|
||||
|
||||
Sphinx supports changing the appearance of its HTML output via *themes*. A
|
||||
theme is a collection of HTML templates, stylesheet(s) and other static files.
|
||||
Additionally, it has a configuration file which specifies from which theme to
|
||||
@@ -15,274 +21,6 @@ Themes are meant to be project-unaware, so they can be used for different
|
||||
projects without change.
|
||||
|
||||
|
||||
Using a theme
|
||||
-------------
|
||||
|
||||
Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these
|
||||
do not need to be installed, you only need to set the :confval:`html_theme`
|
||||
config value. For example, to enable the ``classic`` theme, add the following
|
||||
to :file:`conf.py`::
|
||||
|
||||
html_theme = "classic"
|
||||
|
||||
You can also set theme-specific options using the :confval:`html_theme_options`
|
||||
config value. These options are generally used to change the look and feel of
|
||||
the theme. For example, to place the sidebar on the right side and a black
|
||||
background for the relation bar (the bar with the navigation links at the
|
||||
page's top and bottom), add the following :file:`conf.py`::
|
||||
|
||||
html_theme_options = {
|
||||
"rightsidebar": "true",
|
||||
"relbarbgcolor": "black"
|
||||
}
|
||||
|
||||
If the theme does not come with Sphinx, it can be in two static forms or as a
|
||||
Python package. For the static forms, either a directory (containing
|
||||
:file:`theme.conf` and other needed files), or a zip file with the same
|
||||
contents is supported. The directory or zipfile must be put where Sphinx can
|
||||
find it; for this there is the config value :confval:`html_theme_path`. This
|
||||
can be a list of directories, relative to the directory containing
|
||||
:file:`conf.py`, that can contain theme directories or zip files. For example,
|
||||
if you have a theme in the file :file:`blue.zip`, you can put it right in the
|
||||
directory containing :file:`conf.py` and use this configuration::
|
||||
|
||||
html_theme = "blue"
|
||||
html_theme_path = ["."]
|
||||
|
||||
The third form is a Python package. If a theme you want to use is distributed
|
||||
as a Python package, you can use it after installing
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# installing theme package
|
||||
$ pip install sphinxjp.themes.dotted
|
||||
|
||||
# use it in your conf.py
|
||||
html_theme = "dotted"
|
||||
|
||||
|
||||
.. _builtin-themes:
|
||||
|
||||
Builtin themes
|
||||
--------------
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |alabaster| | |classic| |
|
||||
| | |
|
||||
| *alabaster* | *classic* |
|
||||
+--------------------+--------------------+
|
||||
| |sphinxdoc| | |scrolls| |
|
||||
| | |
|
||||
| *sphinxdoc* | *scrolls* |
|
||||
+--------------------+--------------------+
|
||||
| |agogo| | |traditional| |
|
||||
| | |
|
||||
| *agogo* | *traditional* |
|
||||
+--------------------+--------------------+
|
||||
| |nature| | |haiku| |
|
||||
| | |
|
||||
| *nature* | *haiku* |
|
||||
+--------------------+--------------------+
|
||||
| |pyramid| | |bizstyle| |
|
||||
| | |
|
||||
| *pyramid* | *bizstyle* |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |alabaster| image:: themes/alabaster.png
|
||||
.. |classic| image:: themes/classic.png
|
||||
.. |sphinxdoc| image:: themes/sphinxdoc.png
|
||||
.. |scrolls| image:: themes/scrolls.png
|
||||
.. |agogo| image:: themes/agogo.png
|
||||
.. |traditional| image:: themes/traditional.png
|
||||
.. |nature| image:: themes/nature.png
|
||||
.. |haiku| image:: themes/haiku.png
|
||||
.. |pyramid| image:: themes/pyramid.png
|
||||
.. |bizstyle| image:: themes/bizstyle.png
|
||||
|
||||
Sphinx comes with a selection of themes to choose from.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
These themes are:
|
||||
|
||||
**basic**
|
||||
This is a basically unstyled layout used as the base for the
|
||||
other themes, and usable as the base for custom themes as well. The HTML
|
||||
contains all important elements like sidebar and relation bar. There are
|
||||
these options (which are inherited by the other themes):
|
||||
|
||||
- **nosidebar** (true or false): Don't include the sidebar. Defaults to
|
||||
``False``.
|
||||
|
||||
- **sidebarwidth** (int or str): Width of the sidebar in pixels.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Defaults to 230 pixels.
|
||||
|
||||
- **body_min_width** (int or str): Minimal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 0 if you don't want
|
||||
a width limit. Defaults may depend on the theme (often 450px).
|
||||
|
||||
- **body_max_width** (int or str): Maximal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 'none' if you don't
|
||||
want a width limit. Defaults may depend on the theme (often 800px).
|
||||
|
||||
**alabaster**
|
||||
`Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
|
||||
(especially as used in his Requests project), which was itself originally
|
||||
based on @mitsuhiko's theme used for Flask & related projects. Refer to its
|
||||
`installation page`_ for information on how to configure
|
||||
:confval:`html_sidebars` for its use.
|
||||
|
||||
.. _Alabaster theme: https://pypi.org/project/alabaster/
|
||||
.. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
|
||||
|
||||
**classic**
|
||||
This is the classic theme, which looks like `the Python 2
|
||||
documentation <https://docs.python.org/2/>`_. It can be customized via
|
||||
these options:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **stickysidebar** (true or false): Make the sidebar "fixed" so that it
|
||||
doesn't scroll out of view for long body content. This may not work well
|
||||
with all browsers. Defaults to ``False``.
|
||||
|
||||
- **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
|
||||
snippet that makes the sidebar collapsible via a button on its side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **externalrefs** (true or false): Display external links differently from
|
||||
internal links. Defaults to ``False``.
|
||||
|
||||
There are also various color and font options that can change the color scheme
|
||||
without having to write a custom stylesheet:
|
||||
|
||||
- **footerbgcolor** (CSS color): Background color for the footer line.
|
||||
- **footertextcolor** (CSS color): Text color for the footer line.
|
||||
- **sidebarbgcolor** (CSS color): Background color for the sidebar.
|
||||
- **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
|
||||
button (used when *collapsiblesidebar* is ``True``).
|
||||
- **sidebartextcolor** (CSS color): Text color for the sidebar.
|
||||
- **sidebarlinkcolor** (CSS color): Link color for the sidebar.
|
||||
- **relbarbgcolor** (CSS color): Background color for the relation bar.
|
||||
- **relbartextcolor** (CSS color): Text color for the relation bar.
|
||||
- **relbarlinkcolor** (CSS color): Link color for the relation bar.
|
||||
- **bgcolor** (CSS color): Body background color.
|
||||
- **textcolor** (CSS color): Body text color.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **visitedlinkcolor** (CSS color): Body color for visited links.
|
||||
- **headbgcolor** (CSS color): Background color for headings.
|
||||
- **headtextcolor** (CSS color): Text color for headings.
|
||||
- **headlinkcolor** (CSS color): Link color for headings.
|
||||
- **codebgcolor** (CSS color): Background color for code blocks.
|
||||
- **codetextcolor** (CSS color): Default text color for code blocks, if not
|
||||
set differently by the highlighting style.
|
||||
|
||||
- **bodyfont** (CSS font-family): Font for normal text.
|
||||
- **headfont** (CSS font-family): Font for headings.
|
||||
|
||||
**sphinxdoc**
|
||||
The theme originally used by this documentation. It features
|
||||
a sidebar on the right side. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
.. note::
|
||||
|
||||
The Sphinx documentation now uses
|
||||
`an adjusted version of the sphinxdoc theme
|
||||
<https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
|
||||
|
||||
**scrolls**
|
||||
A more lightweight theme, based on `the Jinja documentation
|
||||
<http://jinja.pocoo.org/>`_. The following color options are available:
|
||||
|
||||
- **headerbordercolor**
|
||||
- **subheadlinecolor**
|
||||
- **linkcolor**
|
||||
- **visitedlinkcolor**
|
||||
- **admonitioncolor**
|
||||
|
||||
**agogo**
|
||||
A theme created by Andi Albrecht. The following options are supported:
|
||||
|
||||
- **bodyfont** (CSS font family): Font for normal text.
|
||||
- **headerfont** (CSS font family): Font for headings.
|
||||
- **pagewidth** (CSS length): Width of the page content, default 70em.
|
||||
- **documentwidth** (CSS length): Width of the document (without sidebar),
|
||||
default 50em.
|
||||
- **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
|
||||
- **bgcolor** (CSS color): Background color.
|
||||
- **headerbg** (CSS value for "background"): background for the header area,
|
||||
default a grayish gradient.
|
||||
- **footerbg** (CSS value for "background"): background for the footer area,
|
||||
default a light gray gradient.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
|
||||
headings.
|
||||
- **headerlinkcolor** (CSS color): Color for the backreference link in
|
||||
headings.
|
||||
- **textalign** (CSS *text-align* value): Text alignment for the body, default
|
||||
is ``justify``.
|
||||
|
||||
**nature**
|
||||
A greenish theme. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
**pyramid**
|
||||
A theme from the Pyramid web framework project, designed by Blaise Laflamme.
|
||||
There are currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**haiku**
|
||||
A theme without sidebar inspired by the `Haiku OS user guide
|
||||
<https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following
|
||||
options are supported:
|
||||
|
||||
- **full_logo** (true or false, default ``False``): If this is true, the
|
||||
header will only show the :confval:`html_logo`. Use this for large logos.
|
||||
If this is false, the logo (if present) will be shown floating right, and
|
||||
the documentation title will be put in the header.
|
||||
|
||||
- **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
|
||||
**hoverlinkcolor** (CSS colors): Colors for various body elements.
|
||||
|
||||
**traditional**
|
||||
A theme resembling the old Python documentation. There are
|
||||
currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**epub**
|
||||
A theme for the epub builder. This theme tries to save visual
|
||||
space which is a sparse resource on ebook readers. The following options
|
||||
are supported:
|
||||
|
||||
- **relbar1** (true or false, default ``True``): If this is true, the
|
||||
`relbar1` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
- **footer** (true or false, default ``True``): If this is true, the
|
||||
`footer` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
**bizstyle**
|
||||
A simple bluish theme. The following options are supported
|
||||
beyond *nosidebar* and *sidebarwidth*:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
|
||||
|
||||
.. versionchanged:: 1.3
|
||||
The 'default' theme has been renamed to 'classic'. 'default' is still
|
||||
available, however it will emit a notice that it is an alias for the new
|
||||
'alabaster' theme.
|
||||
|
||||
|
||||
Creating themes
|
||||
---------------
|
||||
|
||||
@@ -412,41 +150,3 @@ is built with the classic theme, the output directory will contain a
|
||||
.. [1] It is not an executable Python file, as opposed to :file:`conf.py`,
|
||||
because that would pose an unnecessary security risk if themes are
|
||||
shared.
|
||||
|
||||
|
||||
Third Party Themes
|
||||
------------------
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |sphinx_rtd_theme| | |
|
||||
| | |
|
||||
| *sphinx_rtd_theme* | |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |sphinx_rtd_theme| image:: themes/sphinx_rtd_theme.png
|
||||
|
||||
There are many third-party themes available. Some of these are general use,
|
||||
while others are specific to an individual project. A section of third-party
|
||||
themes is listed below. Many more can be found on PyPI__, GitHub__ and
|
||||
sphinx-themes.org__.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
**sphinx_rtd_theme**
|
||||
`Read the Docs Sphinx Theme`_.
|
||||
This is a mobile-friendly sphinx theme that was made for readthedocs.org.
|
||||
View a working demo over on readthedocs.org. You can get install and options
|
||||
information at `Read the Docs Sphinx Theme`_ page.
|
||||
|
||||
.. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
**sphinx_rtd_theme** has become optional.
|
||||
|
||||
.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
|
||||
.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
|
||||
.. __: https://sphinx-themes.org/
|
||||
|
||||
@@ -816,7 +816,7 @@ that use Sphinx's HTMLWriter class.
|
||||
.. confval:: html_theme
|
||||
|
||||
The "theme" that the HTML output should use. See the :doc:`section about
|
||||
theming </theming>`. The default is ``'alabaster'``.
|
||||
theming </usage/theming>`. The default is ``'alabaster'``.
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
|
||||
@@ -320,7 +320,7 @@ More topics to be covered
|
||||
|
||||
- :doc:`Other extensions </usage/extensions/index>`:
|
||||
- Static files
|
||||
- :doc:`Selecting a theme </theming>`
|
||||
- :doc:`Selecting a theme </usage/theming>`
|
||||
- :doc:`/usage/advanced/setuptools`
|
||||
- :ref:`Templating <templating>`
|
||||
- Using extensions
|
||||
|
||||
339
doc/usage/theming.rst
Normal file
339
doc/usage/theming.rst
Normal file
@@ -0,0 +1,339 @@
|
||||
.. highlight:: python
|
||||
|
||||
HTML
|
||||
====
|
||||
|
||||
Sphinx provides a number of builders for HTML and HTML-based formats.
|
||||
|
||||
Builders
|
||||
--------
|
||||
|
||||
.. todo:: Populate when the 'builders' document is split up.
|
||||
|
||||
|
||||
Themes
|
||||
------
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
.. note::
|
||||
|
||||
This section provides information about using pre-existing HTML themes. If
|
||||
you wish to create your own theme, refer to :doc:`/theming`.
|
||||
|
||||
Sphinx supports changing the appearance of its HTML output via *themes*. A
|
||||
theme is a collection of HTML templates, stylesheet(s) and other static files.
|
||||
Additionally, it has a configuration file which specifies from which theme to
|
||||
inherit, which highlighting style to use, and what options exist for customizing
|
||||
the theme's look and feel.
|
||||
|
||||
Themes are meant to be project-unaware, so they can be used for different
|
||||
projects without change.
|
||||
|
||||
Using a theme
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these
|
||||
do not need to be installed, you only need to set the :confval:`html_theme`
|
||||
config value. For example, to enable the ``classic`` theme, add the following
|
||||
to :file:`conf.py`::
|
||||
|
||||
html_theme = "classic"
|
||||
|
||||
You can also set theme-specific options using the :confval:`html_theme_options`
|
||||
config value. These options are generally used to change the look and feel of
|
||||
the theme. For example, to place the sidebar on the right side and a black
|
||||
background for the relation bar (the bar with the navigation links at the
|
||||
page's top and bottom), add the following :file:`conf.py`::
|
||||
|
||||
html_theme_options = {
|
||||
"rightsidebar": "true",
|
||||
"relbarbgcolor": "black"
|
||||
}
|
||||
|
||||
If the theme does not come with Sphinx, it can be in two static forms or as a
|
||||
Python package. For the static forms, either a directory (containing
|
||||
:file:`theme.conf` and other needed files), or a zip file with the same
|
||||
contents is supported. The directory or zipfile must be put where Sphinx can
|
||||
find it; for this there is the config value :confval:`html_theme_path`. This
|
||||
can be a list of directories, relative to the directory containing
|
||||
:file:`conf.py`, that can contain theme directories or zip files. For example,
|
||||
if you have a theme in the file :file:`blue.zip`, you can put it right in the
|
||||
directory containing :file:`conf.py` and use this configuration::
|
||||
|
||||
html_theme = "blue"
|
||||
html_theme_path = ["."]
|
||||
|
||||
The third form is a Python package. If a theme you want to use is distributed
|
||||
as a Python package, you can use it after installing
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# installing theme package
|
||||
$ pip install sphinxjp.themes.dotted
|
||||
|
||||
Once installed, this can be used in the same manner as a directory or
|
||||
zipfile-based theme::
|
||||
|
||||
html_theme = "dotted"
|
||||
|
||||
For more information on the design of themes, including information about
|
||||
writing your own themes, refer to :doc:`/theming`.
|
||||
|
||||
.. _builtin-themes:
|
||||
|
||||
Builtin themes
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |alabaster| | |classic| |
|
||||
| | |
|
||||
| *alabaster* | *classic* |
|
||||
+--------------------+--------------------+
|
||||
| |sphinxdoc| | |scrolls| |
|
||||
| | |
|
||||
| *sphinxdoc* | *scrolls* |
|
||||
+--------------------+--------------------+
|
||||
| |agogo| | |traditional| |
|
||||
| | |
|
||||
| *agogo* | *traditional* |
|
||||
+--------------------+--------------------+
|
||||
| |nature| | |haiku| |
|
||||
| | |
|
||||
| *nature* | *haiku* |
|
||||
+--------------------+--------------------+
|
||||
| |pyramid| | |bizstyle| |
|
||||
| | |
|
||||
| *pyramid* | *bizstyle* |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |alabaster| image:: /_static/themes/alabaster.png
|
||||
.. |classic| image:: /_static/themes/classic.png
|
||||
.. |sphinxdoc| image:: /_static/themes/sphinxdoc.png
|
||||
.. |scrolls| image:: /_static/themes/scrolls.png
|
||||
.. |agogo| image:: /_static/themes/agogo.png
|
||||
.. |traditional| image:: /_static/themes/traditional.png
|
||||
.. |nature| image:: /_static/themes/nature.png
|
||||
.. |haiku| image:: /_static/themes/haiku.png
|
||||
.. |pyramid| image:: /_static/themes/pyramid.png
|
||||
.. |bizstyle| image:: /_static/themes/bizstyle.png
|
||||
|
||||
Sphinx comes with a selection of themes to choose from.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
These themes are:
|
||||
|
||||
**basic**
|
||||
This is a basically unstyled layout used as the base for the
|
||||
other themes, and usable as the base for custom themes as well. The HTML
|
||||
contains all important elements like sidebar and relation bar. There are
|
||||
these options (which are inherited by the other themes):
|
||||
|
||||
- **nosidebar** (true or false): Don't include the sidebar. Defaults to
|
||||
``False``.
|
||||
|
||||
- **sidebarwidth** (int or str): Width of the sidebar in pixels.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Defaults to 230 pixels.
|
||||
|
||||
- **body_min_width** (int or str): Minimal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 0 if you don't want
|
||||
a width limit. Defaults may depend on the theme (often 450px).
|
||||
|
||||
- **body_max_width** (int or str): Maximal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 'none' if you don't
|
||||
want a width limit. Defaults may depend on the theme (often 800px).
|
||||
|
||||
**alabaster**
|
||||
`Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
|
||||
(especially as used in his Requests project), which was itself originally
|
||||
based on @mitsuhiko's theme used for Flask & related projects. Refer to its
|
||||
`installation page`_ for information on how to configure
|
||||
:confval:`html_sidebars` for its use.
|
||||
|
||||
.. _Alabaster theme: https://pypi.org/project/alabaster/
|
||||
.. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
|
||||
|
||||
**classic**
|
||||
This is the classic theme, which looks like `the Python 2
|
||||
documentation <https://docs.python.org/2/>`_. It can be customized via
|
||||
these options:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **stickysidebar** (true or false): Make the sidebar "fixed" so that it
|
||||
doesn't scroll out of view for long body content. This may not work well
|
||||
with all browsers. Defaults to ``False``.
|
||||
|
||||
- **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
|
||||
snippet that makes the sidebar collapsible via a button on its side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **externalrefs** (true or false): Display external links differently from
|
||||
internal links. Defaults to ``False``.
|
||||
|
||||
There are also various color and font options that can change the color scheme
|
||||
without having to write a custom stylesheet:
|
||||
|
||||
- **footerbgcolor** (CSS color): Background color for the footer line.
|
||||
- **footertextcolor** (CSS color): Text color for the footer line.
|
||||
- **sidebarbgcolor** (CSS color): Background color for the sidebar.
|
||||
- **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
|
||||
button (used when *collapsiblesidebar* is ``True``).
|
||||
- **sidebartextcolor** (CSS color): Text color for the sidebar.
|
||||
- **sidebarlinkcolor** (CSS color): Link color for the sidebar.
|
||||
- **relbarbgcolor** (CSS color): Background color for the relation bar.
|
||||
- **relbartextcolor** (CSS color): Text color for the relation bar.
|
||||
- **relbarlinkcolor** (CSS color): Link color for the relation bar.
|
||||
- **bgcolor** (CSS color): Body background color.
|
||||
- **textcolor** (CSS color): Body text color.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **visitedlinkcolor** (CSS color): Body color for visited links.
|
||||
- **headbgcolor** (CSS color): Background color for headings.
|
||||
- **headtextcolor** (CSS color): Text color for headings.
|
||||
- **headlinkcolor** (CSS color): Link color for headings.
|
||||
- **codebgcolor** (CSS color): Background color for code blocks.
|
||||
- **codetextcolor** (CSS color): Default text color for code blocks, if not
|
||||
set differently by the highlighting style.
|
||||
|
||||
- **bodyfont** (CSS font-family): Font for normal text.
|
||||
- **headfont** (CSS font-family): Font for headings.
|
||||
|
||||
**sphinxdoc**
|
||||
The theme originally used by this documentation. It features
|
||||
a sidebar on the right side. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
.. note::
|
||||
|
||||
The Sphinx documentation now uses
|
||||
`an adjusted version of the sphinxdoc theme
|
||||
<https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
|
||||
|
||||
**scrolls**
|
||||
A more lightweight theme, based on `the Jinja documentation
|
||||
<http://jinja.pocoo.org/>`_. The following color options are available:
|
||||
|
||||
- **headerbordercolor**
|
||||
- **subheadlinecolor**
|
||||
- **linkcolor**
|
||||
- **visitedlinkcolor**
|
||||
- **admonitioncolor**
|
||||
|
||||
**agogo**
|
||||
A theme created by Andi Albrecht. The following options are supported:
|
||||
|
||||
- **bodyfont** (CSS font family): Font for normal text.
|
||||
- **headerfont** (CSS font family): Font for headings.
|
||||
- **pagewidth** (CSS length): Width of the page content, default 70em.
|
||||
- **documentwidth** (CSS length): Width of the document (without sidebar),
|
||||
default 50em.
|
||||
- **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
|
||||
- **bgcolor** (CSS color): Background color.
|
||||
- **headerbg** (CSS value for "background"): background for the header area,
|
||||
default a grayish gradient.
|
||||
- **footerbg** (CSS value for "background"): background for the footer area,
|
||||
default a light gray gradient.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
|
||||
headings.
|
||||
- **headerlinkcolor** (CSS color): Color for the backreference link in
|
||||
headings.
|
||||
- **textalign** (CSS *text-align* value): Text alignment for the body, default
|
||||
is ``justify``.
|
||||
|
||||
**nature**
|
||||
A greenish theme. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
**pyramid**
|
||||
A theme from the Pyramid web framework project, designed by Blaise Laflamme.
|
||||
There are currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**haiku**
|
||||
A theme without sidebar inspired by the `Haiku OS user guide
|
||||
<https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following
|
||||
options are supported:
|
||||
|
||||
- **full_logo** (true or false, default ``False``): If this is true, the
|
||||
header will only show the :confval:`html_logo`. Use this for large logos.
|
||||
If this is false, the logo (if present) will be shown floating right, and
|
||||
the documentation title will be put in the header.
|
||||
|
||||
- **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
|
||||
**hoverlinkcolor** (CSS colors): Colors for various body elements.
|
||||
|
||||
**traditional**
|
||||
A theme resembling the old Python documentation. There are
|
||||
currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**epub**
|
||||
A theme for the epub builder. This theme tries to save visual
|
||||
space which is a sparse resource on ebook readers. The following options
|
||||
are supported:
|
||||
|
||||
- **relbar1** (true or false, default ``True``): If this is true, the
|
||||
`relbar1` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
- **footer** (true or false, default ``True``): If this is true, the
|
||||
`footer` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
**bizstyle**
|
||||
A simple bluish theme. The following options are supported
|
||||
beyond *nosidebar* and *sidebarwidth*:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
|
||||
|
||||
.. versionchanged:: 1.3
|
||||
The 'default' theme has been renamed to 'classic'. 'default' is still
|
||||
available, however it will emit a notice that it is an alias for the new
|
||||
'alabaster' theme.
|
||||
|
||||
Third Party Themes
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |sphinx_rtd_theme| | |
|
||||
| | |
|
||||
| *sphinx_rtd_theme* | |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |sphinx_rtd_theme| image:: /_static/themes/sphinx_rtd_theme.png
|
||||
|
||||
There are many third-party themes available. Some of these are general use,
|
||||
while others are specific to an individual project. A section of third-party
|
||||
themes is listed below. Many more can be found on PyPI__, GitHub__ and
|
||||
sphinx-themes.org__.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
**sphinx_rtd_theme**
|
||||
`Read the Docs Sphinx Theme`_.
|
||||
This is a mobile-friendly sphinx theme that was made for readthedocs.org.
|
||||
View a working demo over on readthedocs.org. You can get install and options
|
||||
information at `Read the Docs Sphinx Theme`_ page.
|
||||
|
||||
.. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
**sphinx_rtd_theme** has become optional.
|
||||
|
||||
.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
|
||||
.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
|
||||
.. __: https://sphinx-themes.org/
|
||||
Reference in New Issue
Block a user