diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/development/html_themes/index.rst (renamed from doc/development/theming.rst) | 37 |
1 files changed, 30 insertions, 7 deletions
diff --git a/doc/development/theming.rst b/doc/development/html_themes/index.rst index 13a5802..8724398 100644 --- a/doc/development/theming.rst +++ b/doc/development/html_themes/index.rst @@ -1,3 +1,5 @@ +.. _extension-html-theme: + HTML theme development ====================== @@ -112,7 +114,7 @@ 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: -.. sourcecode:: ini +.. code-block:: ini [theme] inherit = base theme @@ -222,6 +224,11 @@ If your theme package contains two or more themes, please call Templating ---------- +.. toctree:: + :hidden: + + templating + The :doc:`guide to templating <templating>` is helpful if you want to write your own templates. What is important to keep in mind is the order in which Sphinx searches for templates: @@ -247,12 +254,28 @@ template static files as well as HTML files. Therefore, Sphinx supports so-called "static templates", like this: If the name of a file in the ``static/`` directory of a theme (or in the user's -static path, for that matter) ends with ``_t``, it will be processed by the -template engine. The ``_t`` will be left from the final file name. For -example, the *classic* theme has a file ``static/classic.css_t`` which uses -templating to put the color options into the stylesheet. When a documentation -project is built with the classic theme, the output directory will contain a -``_static/classic.css`` file where all template tags have been processed. +static path) ends with ``.jinja`` or ``_t``, it will be processed by the +template engine. The suffix will be removed from the final file name. + +For example, a theme with a ``static/theme_styles.css.jinja`` file could use +templating to put options into the stylesheet. +When a documentation project is built with that theme, +the output directory will contain a ``_static/theme_styles.css`` file +where all template tags have been processed. + +.. versionchanged:: 7.4 + + The preferred suffix for static templates is now ``.jinja``, in line with + the Jinja project's `recommended file extension`_. + + The ``_t`` file suffix for static templates is now considered 'legacy', and + support may eventually be removed. + + If a static template with either a ``_t`` suffix or a ``.jinja`` suffix is + detected, it will be processed by the template engine, with the suffix + removed from the final file name. + + .. _recommended file extension: https://jinja.palletsprojects.com/en/latest/templates/#template-file-extension Use custom page metadata in HTML templates |