diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/development/html_themes/index.rst (renamed from doc/development/theming.rst) | 37 | ||||
| -rw-r--r-- | doc/development/html_themes/templating.rst (renamed from doc/development/templating.rst) | 8 |
2 files changed, 34 insertions, 11 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 diff --git a/doc/development/templating.rst b/doc/development/html_themes/templating.rst index 016b8b8..e2de045 100644 --- a/doc/development/templating.rst +++ b/doc/development/html_themes/templating.rst @@ -289,8 +289,8 @@ in the future. .. data:: has_source - True if the reST document sources are copied (if :confval:`html_copy_source` - is ``True``). + True if the reStructuredText document sources are copied + (if :confval:`html_copy_source` is ``True``). .. data:: language @@ -326,8 +326,8 @@ in the future. .. data:: pagename The "page name" of the current file, i.e. either the document name if the - file is generated from a reST source, or the equivalent hierarchical name - relative to the output directory + file is generated from a reStructuredText source, + or the equivalent hierarchical name relative to the output directory (``[directory/]filename_without_extension``). .. data:: project |