diff options
Diffstat (limited to 'doc/usage/theming.rst')
| -rw-r--r-- | doc/usage/theming.rst | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst new file mode 100644 index 0000000..c33c7d4 --- /dev/null +++ b/doc/usage/theming.rst @@ -0,0 +1,364 @@ +.. highlight:: python + +.. _html-themes: + +HTML Theming +============ + +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:`/development/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:: console + + # 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:`/development/theming`. + +.. _builtin-themes: + +Builtin themes +~~~~~~~~~~~~~~ + +.. cssclass:: longtable, standard + ++--------------------+--------------------+ +| **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. + +Note that from these themes only the Alabaster and Scrolls themes are +mobile-optimated, the other themes resort to horizontal scrolling +if the screen is too narrow. + +.. 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). + + - **navigation_with_keys** (true or false): Allow navigating + with the following keyboard shortcuts: + + - :kbd:`Left arrow`: previous page + - :kbd:`Right arrow`: next page + + Defaults to ``False``. + + - **enable_search_shortcuts** (true or false): Allow jumping to the search box + with :kbd:`/` and allow removal of search highlighting with :kbd:`Esc`. + + Defaults to ``True``. + + - **globaltoc_collapse** (true or false): Only expand subsections + of the current document in ``globaltoc.html`` + (see :confval:`html_sidebars`). + Defaults to ``True``. + + .. versionadded:: 3.1 + + - **globaltoc_includehidden** (true or false): Show even those + subsections in ``globaltoc.html`` (see :confval:`html_sidebars`) + which have been included with the ``:hidden:`` flag of the + :rst:dir:`toctree` directive. + Defaults to ``False``. + + .. versionadded:: 3.1 + + - **globaltoc_maxdepth** (int): The maximum depth of the toctree in + ``globaltoc.html`` (see :confval:`html_sidebars`). Set it to -1 to allow + unlimited depth. Defaults to the max depth selected in the toctree directive. + + .. versionadded:: 3.2 + +**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 + <https://jinja.palletsprojects.com/>`_. 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. + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``True``. + - **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: + +Third Party Themes +~~~~~~~~~~~~~~~~~~ + +There are many third-party themes created for Sphinx. Some of these are for +general use, while others are specific to an individual project. + +sphinx-themes.org__ is a gallery that showcases various themes for Sphinx, +with demo documentation rendered under each theme. Themes can also be found +on PyPI__ (using the classifier ``Framework :: Sphinx :: Theme``), GitHub__ +and GitLab__. + +.. __: https://sphinx-themes.org/ +.. __: 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 +.. __: https://gitlab.com/explore?name=sphinx+theme |