From 5de84c9242643f786eff03726286578726d7d390 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 5 Jun 2024 18:20:59 +0200 Subject: Merging upstream version 7.3.7. Signed-off-by: Daniel Baumann --- doc/development/theming.rst | 125 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 108 insertions(+), 17 deletions(-) (limited to 'doc/development/theming.rst') diff --git a/doc/development/theming.rst b/doc/development/theming.rst index 538dcaf..13a5802 100644 --- a/doc/development/theming.rst +++ b/doc/development/theming.rst @@ -30,11 +30,85 @@ Creating themes Themes take the form of either a directory or a zipfile (whose name is the theme name), containing the following: -* A :file:`theme.conf` file. +* Either a :file:`theme.toml` file (preferred) or a :file:`theme.conf` file. * HTML templates, if needed. * A ``static/`` directory containing any static files that will be copied to the output static directory on build. These can be images, styles, script files. +Theme configuration (``theme.toml``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :file:`theme.toml` file is a TOML_ document, +containing two tables: ``[theme]`` and ``[options]``. + +The ``[theme]`` table defines the theme's settings: + +* **inherit** (string): The name of the base theme from which to inherit + settings, options, templates, and static files. + All static files from theme 'ancestors' will be used. + The theme will use all options defined in inherited themes. + Finally, inherited themes will be used to locate missing templates + (for example, if ``"basic"`` is used as the base theme, most templates will + already be defined). + + If set to ``"none"``, the theme will not inherit from any other theme. + Inheritance is recursive, forming a chain of inherited themes + (e.g. ``default`` -> ``classic`` -> ``basic`` -> ``none``). + +* **stylesheets** (list of strings): A list of CSS filenames which will be + included in generated HTML header. + Setting the :confval:`html_style` config value will override this setting. + + Other mechanisms for including multiple stylesheets include ``@import`` in CSS + or using a custom HTML template with appropriate ```` tags. + +* **sidebars** (list of strings): A list of sidebar templates. + This can be overridden by the user via the :confval:`html_sidebars` config value. + +* **pygments_style** (table): A TOML table defining the names of Pygments styles + to use for highlighting syntax. + The table has two recognised keys: ``default`` and ``dark``. + The style defined in the ``dark`` key will be used when + the CSS media query ``(prefers-color-scheme: dark)`` evaluates to true. + + ``[theme.pygments_style.default]`` can be overridden by the user via the + :confval:`pygments_style` config value. + +The ``[options]`` table defines the options for the theme. +It is structured such that each key-value pair corresponds to a variable name +and the corresponding default value. +These options can be overridden by the user in :confval:`html_theme_options` +and are accessible from all templates as ``theme_``. + +.. versionadded:: 7.3 + ``theme.toml`` support. + +.. _TOML: https://toml.io/en/ + +Exemplar :file:`theme.toml` file: + +.. code-block:: toml + + [theme] + inherit = "basic" + stylesheets = [ + "main-CSS-stylesheet.css", + ] + sidebars = [ + "localtoc.html", + "relations.html", + "sourcelink.html", + "searchbox.html", + ] + # Style names from https://pygments.org/styles/ + pygments_style = { default = "style_name", dark = "dark_style" } + + [options] + variable = "default value" + +Theme configuration (``theme.conf``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The :file:`theme.conf` file is in INI format [1]_ (readable by the standard Python :mod:`configparser` module) and has the following structure: @@ -86,6 +160,24 @@ Python :mod:`configparser` module) and has the following structure: The stylesheet setting accepts multiple CSS filenames +Convert ``theme.conf`` to ``theme.toml`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +INI-style theme configuration files (``theme.conf``) can be converted to TOML +via a helper programme distributed with Sphinx. +This is intended for one-time use, and may be removed without notice in a future +version of Sphinx. + +.. code-block:: console + + $ python -m sphinx.theming conf_to_toml [THEME DIRECTORY PATH] + +The required argument is a path to a directory containing a ``theme.conf`` file. +The programme will write a ``theme.toml`` file in the same directory, +and will not modify the original ``theme.conf`` file. + +.. versionadded:: 7.3 + .. _distribute-your-theme: Distribute your theme as a Python package @@ -95,21 +187,20 @@ As a way to distribute your theme, you can use a Python package. This makes it easier for users to set up your theme. To distribute your theme as a Python package, please define an entry point -called ``sphinx.html_themes`` in your ``setup.py`` file, and write a ``setup()`` -function to register your themes using ``add_html_theme()`` API in it:: - - # 'setup.py' - setup( - ... - entry_points = { - 'sphinx.html_themes': [ - 'name_of_theme = your_package', - ] - }, - ... - ) - - # 'your_package.py' +called ``sphinx.html_themes`` in your ``pyproject.toml`` file, +and write a ``setup()`` function to register your theme +using the :meth:`~sphinx.application.Sphinx.add_html_theme` API: + +.. code-block:: toml + + # pyproject.toml + + [project.entry-points."sphinx.html_themes"] + name_of_theme = "your_theme_package" + +.. code-block:: python + + # your_theme_package.py from os import path def setup(app): @@ -142,7 +233,7 @@ searches for templates: When extending a template in the base theme with the same name, use the theme name as an explicit directory: ``{% extends "basic/layout.html" %}``. From a user ``templates_path`` template, you can still use the "exclamation mark" -syntax as described in the templating document. +syntax as :ref:`described in the templating document `. .. _theming-static-templates: -- cgit v1.2.3