diff options
Diffstat (limited to 'doc/development/html_themes')
| -rw-r--r-- | doc/development/html_themes/index.rst | 456 | ||||
| -rw-r--r-- | doc/development/html_themes/templating.rst | 479 |
2 files changed, 935 insertions, 0 deletions
diff --git a/doc/development/html_themes/index.rst b/doc/development/html_themes/index.rst new file mode 100644 index 0000000..8724398 --- /dev/null +++ b/doc/development/html_themes/index.rst @@ -0,0 +1,456 @@ +.. _extension-html-theme: + +HTML theme development +====================== + +.. 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 +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. + +.. note:: + + See :ref:`dev-extensions` for more information that may + be helpful in developing themes. + + +Creating themes +--------------- + +Themes take the form of either a directory or a zipfile (whose name is the +theme name), containing the following: + +* 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 ``<link rel="stylesheet">`` 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_<name>``. + +.. 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: + +.. code-block:: ini + + [theme] + inherit = base theme + stylesheet = main CSS name + pygments_style = stylename + sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html + + [options] + variable = default value + +* The **inherit** setting gives the name of a "base theme", or ``none``. The + base theme will be used to locate missing templates (most themes will not have + to supply most templates if they use ``basic`` as the base theme), its options + will be inherited, and all of its static files will be used as well. If you + want to also inherit the stylesheet, include it via CSS' ``@import`` in your + own. + +* The **stylesheet** setting gives a list of CSS filenames separated commas which + will be referenced in the HTML header. You can also use CSS' ``@import`` + technique to include one from the other, or use a custom HTML template that + adds ``<link rel="stylesheet">`` tags as necessary. Setting the + :confval:`html_style` config value will override this setting. + +* The **pygments_style** setting gives the name of a Pygments style to use for + highlighting. This can be overridden by the user in the + :confval:`pygments_style` config value. + +* The **pygments_dark_style** setting gives the name of a Pygments style to use + for highlighting when the CSS media query ``(prefers-color-scheme: dark)`` + evaluates to true. It is injected into the page using + :meth:`~sphinx.application.Sphinx.add_css_file()`. + +* The **sidebars** setting gives the comma separated list of sidebar templates + for constructing sidebars. This can be overridden by the user in the + :confval:`html_sidebars` config value. + +* The **options** section contains pairs of variable names and default values. + These options can be overridden by the user in :confval:`html_theme_options` + and are accessible from all templates as ``theme_<name>``. + +.. versionadded:: 1.7 + sidebar settings + +.. versionchanged:: 5.1 + + 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 +----------------------------------------- + +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 ``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): + app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__))) + +If your theme package contains two or more themes, please call +``add_html_theme()`` twice or more. + +.. versionadded:: 1.2 + 'sphinx_themes' entry_points feature. + +.. deprecated:: 1.6 + ``sphinx_themes`` entry_points has been deprecated. + +.. versionadded:: 1.6 + ``sphinx.html_themes`` entry_points feature. + + +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: + +* First, in the user's ``templates_path`` directories. +* Then, in the selected theme. +* Then, in its base theme, its base's base theme, etc. + +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 :ref:`described in the templating document <templating-primer>`. + + +.. _theming-static-templates: + +Static templates +~~~~~~~~~~~~~~~~ + +Since theme options are meant for the user to configure a theme more easily, +without having to write a custom stylesheet, it is necessary to be able to +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) 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Any key / value pairs in :doc:`field lists </usage/restructuredtext/field-lists>` +that are placed *before* the page's title will be available to the Jinja +template when building the page within the :data:`meta` attribute. For example, +if a page had the following text before its first title: + +.. code-block:: rst + + :mykey: My value + + My first title + -------------- + +Then it could be accessed within a Jinja template like so: + +.. code-block:: jinja + + {%- if meta is mapping %} + {{ meta.get("mykey") }} + {%- endif %} + +Note the check that ``meta`` is a dictionary ("mapping" in Jinja +terminology) to ensure that using it in this way is valid. + + +Defining custom template functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes it is useful to define your own function in Python that you wish to +then use in a template. For example, if you'd like to insert a template value +with logic that depends on the user's configuration in the project, or if you'd +like to include non-trivial checks and provide friendly error messages for +incorrect configuration in the template. + +To define your own template function, you'll need to define two functions +inside your module: + +* A **page context event handler** (or **registration**) function. This is + connected to the :class:`.Sphinx` application via an event callback. +* A **template function** that you will use in your Jinja template. + +First, define the registration function, which accepts the arguments for +:event:`html-page-context`. + +Within the registration function, define the template function that you'd like to +use within Jinja. The template function should return a string or Python objects +(lists, dictionaries) with strings inside that Jinja uses in the templating process + +.. note:: + + The template function will have access to all of the variables that + are passed to the registration function. + +At the end of the registration function, add the template function to the +Sphinx application's context with ``context['template_func'] = template_func``. + +Finally, in your extension's ``setup()`` function, add your registration +function as a callback for :event:`html-page-context`. + +.. code-block:: python + + # The registration function + def setup_my_func(app, pagename, templatename, context, doctree): + # The template function + def my_func(mystring): + return "Your string is %s" % mystring + # Add it to the page's context + context['my_func'] = my_func + + # Your extension's setup function + def setup(app): + app.connect("html-page-context", setup_my_func) + +Now, you will have access to this function in jinja like so: + +.. code-block:: jinja + + <div> + {{ my_func("some string") }} + </div> + + +Add your own static files to the build assets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, Sphinx copies static files on the ``static/`` directory of the template +directory. However, if your package needs to place static files outside of the +``static/`` directory for some reasons, you need to copy them to the ``_static/`` +directory of HTML outputs manually at the build via an event hook. Here is an +example of code to accomplish this: + +.. code-block:: python + + from os import path + from sphinx.util.fileutil import copy_asset_file + + def copy_custom_files(app, exc): + if app.builder.format == 'html' and not exc: + staticdir = path.join(app.builder.outdir, '_static') + copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir) + + def setup(app): + app.connect('build-finished', copy_custom_files) + + +Inject JavaScript based on user configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your extension makes use of JavaScript, it can be useful to allow users +to control its behavior using their Sphinx configuration. However, this can +be difficult to do if your JavaScript comes in the form of a static library +(which will not be built with Jinja). + +There are two ways to inject variables into the JavaScript space based on user +configuration. + +First, you may append ``_t`` to the end of any static files included with your +extension. This will cause Sphinx to process these files with the templating +engine, allowing you to embed variables and control behavior. + +For example, the following JavaScript structure: + +.. code-block:: none + + mymodule/ + ├── _static + │ └── myjsfile.js_t + └── mymodule.py + +Will result in the following static file placed in your HTML's build output: + +.. code-block:: none + + _build/ + └── html + └── _static + └── myjsfile.js + +See :ref:`theming-static-templates` for more information. + +Second, you may use the :meth:`.Sphinx.add_js_file` method without pointing it +to a file. Normally, this method is used to insert a new JavaScript file +into your site. However, if you do *not* pass a file path, but instead pass +a string to the "body" argument, then this text will be inserted as JavaScript +into your site's head. This allows you to insert variables into your project's +JavaScript from Python. + +For example, the following code will read in a user-configured value and then +insert this value as a JavaScript variable, which your extension's JavaScript +code may use: + +.. code-block:: python + + # This function reads in a variable and inserts it into JavaScript + def add_js_variable(app): + # This is a configuration that you've specified for users in `conf.py` + js_variable = app.config['my_javascript_variable'] + js_text = "var my_variable = '%s';" % js_variable + app.add_js_file(None, body=js_text) + # We connect this function to the step after the builder is initialized + def setup(app): + # Tell Sphinx about this configuration variable + app.add_config_value('my_javascript_variable', 0, 'html') + # Run the function after the builder is initialized + app.connect('builder-inited', add_js_variable) + +As a result, in your theme you can use code that depends on the presence of +this variable. Users can control the variable's value by defining it in their +:file:`conf.py` file. + + +.. [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. diff --git a/doc/development/html_themes/templating.rst b/doc/development/html_themes/templating.rst new file mode 100644 index 0000000..e2de045 --- /dev/null +++ b/doc/development/html_themes/templating.rst @@ -0,0 +1,479 @@ +.. highlight:: html+jinja + +.. _templating: + +========== +Templating +========== + +Sphinx uses the `Jinja <https://jinja.palletsprojects.com/>`_ templating engine +for its HTML templates. Jinja is a text-based engine, inspired by Django +templates, so anyone having used Django will already be familiar with it. It +also has excellent documentation for those who need to make themselves familiar +with it. + + +Do I need to use Sphinx's templates to produce HTML? +---------------------------------------------------- + +No. You have several other options: + +* You can write a :class:`~sphinx.application.TemplateBridge` subclass that + calls your template engine of choice, and set the :confval:`template_bridge` + configuration value accordingly. + +* You can :ref:`write a custom builder <writing-builders>` that derives from + :class:`~sphinx.builders.html.StandaloneHTMLBuilder` and calls your template + engine of choice. + +* You can use the :class:`~sphinxcontrib.serializinghtml.PickleHTMLBuilder` that + produces pickle files with the page contents, and postprocess them using a + custom tool, or use them in your Web application. + +.. _templating-primer: + +Jinja/Sphinx Templating Primer +------------------------------ + +The default templating language in Sphinx is Jinja. It's Django/Smarty inspired +and easy to understand. The most important concept in Jinja is :dfn:`template +inheritance`, which means that you can overwrite only specific blocks within a +template, customizing it while also keeping the changes at a minimum. + +To customize the output of your documentation you can override all the templates +(both the layout templates and the child templates) by adding files with the +same name as the original filename into the template directory of the structure +the Sphinx quickstart generated for you. + +Sphinx will look for templates in the folders of :confval:`templates_path` +first, and if it can't find the template it's looking for there, it falls back +to the selected theme's templates. + +A template contains **variables**, which are replaced with values when the +template is evaluated, **tags**, which control the logic of the template and +**blocks** which are used for template inheritance. + +Sphinx's *basic* theme provides base templates with a couple of blocks it will +fill with data. These are located in the :file:`themes/basic` subdirectory of +the Sphinx installation directory, and used by all builtin Sphinx themes. +Templates with the same name in the :confval:`templates_path` override templates +supplied by the selected theme. + +For example, to add a new link to the template area containing related links all +you have to do is to add a new template called ``layout.html`` with the +following contents:: + + {% extends "!layout.html" %} + {% block rootrellink %} + <li><a href="https://project.invalid/">Project Homepage</a> »</li> + {{ super() }} + {% endblock %} + +By prefixing the name of the overridden template with an exclamation mark, +Sphinx will load the layout template from the underlying HTML theme. + +.. important:: + If you override a block, call ``{{ super() }}`` somewhere to render the + block's original content in the extended template -- unless you don't want + that content to show up. + + +Working with the builtin templates +---------------------------------- + +The builtin **basic** theme supplies the templates that all builtin Sphinx +themes are based on. It has the following elements you can override or use: + +Blocks +~~~~~~ + +The following blocks exist in the ``layout.html`` template: + +``doctype`` + The doctype of the output format. By default this is XHTML 1.0 Transitional + as this is the closest to what Sphinx and Docutils generate and it's a good + idea not to change it unless you want to switch to HTML 5 or a different but + compatible XHTML doctype. + +``linktags`` + This block adds a couple of ``<link>`` tags to the head section of the + template. + +``extrahead`` + This block is empty by default and can be used to add extra contents into + the ``<head>`` tag of the generated HTML file. This is the right place to + add references to JavaScript or extra CSS files. + +``relbar1``, ``relbar2`` + This block contains the *relation bar*, the list of related links (the + parent documents on the left, and the links to index, modules etc. on the + right). ``relbar1`` appears before the document, ``relbar2`` after the + document. By default, both blocks are filled; to show the relbar only + before the document, you would override ``relbar2`` like this:: + + {% block relbar2 %}{% endblock %} + +``rootrellink``, ``relbaritems`` + Inside the relbar there are three sections: The ``rootrellink``, the links + from the documentation and the custom ``relbaritems``. The ``rootrellink`` + is a block that by default contains a list item pointing to the root + document by default, the ``relbaritems`` is an empty block. If you + override them to add extra links into the bar make sure that they are list + items and end with the :data:`reldelim1`. + +``document`` + The contents of the document itself. It contains the block "body" where + the individual content is put by subtemplates like ``page.html``. + + .. note:: + In order for the built-in JavaScript search to show a page preview on + the results page, the document or body content should be wrapped in an + HTML element containing the ``role="main"`` attribute. For example:: + + <div role="main"> + {% block document %}{% endblock %} + </div> + +``sidebar1``, ``sidebar2`` + A possible location for a sidebar. ``sidebar1`` appears before the document + and is empty by default, ``sidebar2`` after the document and contains the + default sidebar. If you want to swap the sidebar location override this and + call the ``sidebar`` helper:: + + {% block sidebar1 %}{{ sidebar() }}{% endblock %} + {% block sidebar2 %}{% endblock %} + + (The ``sidebar2`` location for the sidebar is needed by the ``sphinxdoc.css`` + stylesheet, for example.) + +``sidebarlogo`` + The logo location within the sidebar. Override this if you want to place + some content at the top of the sidebar. + +``footer`` + The block for the footer div. If you want a custom footer or markup before + or after it, override this one. + +The following four blocks are *only* used for pages that do not have assigned a +list of custom sidebars in the :confval:`html_sidebars` config value. Their use +is deprecated in favor of separate sidebar templates, which can be included via +:confval:`html_sidebars`. + +``sidebartoc`` + The table of contents within the sidebar. + + .. deprecated:: 1.0 + +``sidebarrel`` + The relation links (previous, next document) within the sidebar. + + .. deprecated:: 1.0 + +``sidebarsourcelink`` + The "Show source" link within the sidebar (normally only shown if this is + enabled by :confval:`html_show_sourcelink`). + + .. deprecated:: 1.0 + +``sidebarsearch`` + The search box within the sidebar. Override this if you want to place some + content at the bottom of the sidebar. + + .. deprecated:: 1.0 + + +Configuration Variables +~~~~~~~~~~~~~~~~~~~~~~~ + +Inside templates you can set a couple of variables used by the layout template +using the ``{% set %}`` tag: + +.. data:: reldelim1 + + The delimiter for the items on the left side of the related bar. This + defaults to ``' »'`` Each item in the related bar ends with the value + of this variable. + +.. data:: reldelim2 + + The delimiter for the items on the right side of the related bar. This + defaults to ``' |'``. Each item except of the last one in the related bar + ends with the value of this variable. + +Overriding works like this:: + + {% extends "!layout.html" %} + {% set reldelim1 = ' >' %} + +.. data:: script_files + + Add additional script files here, like this:: + + {% set script_files = script_files + ["_static/myscript.js"] %} + + .. deprecated:: 1.8.0 + + Please use ``.Sphinx.add_js_file()`` instead. + +Helper Functions +~~~~~~~~~~~~~~~~ + +Sphinx provides various Jinja functions as helpers in the template. You can use +them to generate links or output multiply used elements. + +.. function:: pathto(document) + + Return the path to a Sphinx document as a URL. Use this to refer to built + documents. + +.. function:: pathto(file, 1) + :no-index: + + Return the path to a *file* which is a filename relative to the root of the + generated output. Use this to refer to static files. + +.. function:: hasdoc(document) + + Check if a document with the name *document* exists. + +.. function:: sidebar() + + Return the rendered sidebar. + +.. function:: relbar() + + Return the rendered relation bar. + +.. function:: warning(message) + + Emit a warning message. + +Global Variables +~~~~~~~~~~~~~~~~ + +These global variables are available in every template and are safe to use. +There are more, but most of them are an implementation detail and might change +in the future. + +.. data:: builder + + The name of the builder (e.g. ``html`` or ``htmlhelp``). + +.. data:: copyright + + The value of :confval:`copyright`. + +.. data:: docstitle + + The title of the documentation (the value of :confval:`html_title`), except + when the "single-file" builder is used, when it is set to ``None``. + +.. data:: embedded + + True if the built HTML is meant to be embedded in some viewing application + that handles navigation, not the web browser, such as for HTML help or Qt + help formats. In this case, the sidebar is not included. + +.. data:: favicon_url + + The relative path to the HTML favicon image from the current document, or + URL to the favicon, or ``''``. + + .. versionadded:: 4.0 + +.. data:: file_suffix + + The value of the builder's :attr:`~.SerializingHTMLBuilder.out_suffix` + attribute, i.e. the file name extension that the output files will get. For + a standard HTML builder, this is usually ``.html``. + +.. data:: has_source + + True if the reStructuredText document sources are copied + (if :confval:`html_copy_source` is ``True``). + +.. data:: language + + The value of :confval:`language`. + +.. data:: last_updated + + The build date. + +.. data:: logo_url + + The relative path to the HTML logo image from the current document, or URL + to the logo, or ``''``. + + .. versionadded:: 4.0 + +.. data:: master_doc + + Same as :data:`root_doc`. + + .. versionchanged:: 4.0 + + Renamed to ``root_doc``. + +.. data:: root_doc + + The value of :confval:`root_doc`, for usage with :func:`pathto`. + + .. versionchanged:: 4.0 + + Renamed from ``master_doc``. + +.. data:: pagename + + The "page name" of the current file, i.e. either the document name if the + file is generated from a reStructuredText source, + or the equivalent hierarchical name relative to the output directory + (``[directory/]filename_without_extension``). + +.. data:: project + + The value of :confval:`project`. + +.. data:: release + + The value of :confval:`release`. + +.. data:: rellinks + + A list of links to put at the left side of the relbar, next to "next" and + "prev". This usually contains links to the general index and other indices, + such as the Python module index. If you add something yourself, it must be a + tuple ``(pagename, link title, accesskey, link text)``. + +.. data:: shorttitle + + The value of :confval:`html_short_title`. + +.. data:: show_source + + True if :confval:`html_show_sourcelink` is ``True``. + +.. data:: sphinx_version + + The version of Sphinx used to build represented as a string for example "3.5.1". + +.. data:: sphinx_version_tuple + + The version of Sphinx used to build represented as a tuple of five elements. + For Sphinx version 3.5.1 beta 3 this would be ``(3, 5, 1, 'beta', 3)``. + The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``. + ``final`` always has 0 as the last element. + + .. versionadded:: 4.2 + +.. data:: docutils_version_info + + The version of Docutils used to build represented as a tuple of five elements. + For Docutils version 0.16.1 beta 2 this would be ``(0, 16, 1, 'beta', 2)``. + The fourth element can be one of: ``alpha``, ``beta``, ``candidate``, ``final``. + ``final`` always has 0 as the last element. + + .. versionadded:: 5.0.2 + +.. data:: styles + + A list of the names of the main stylesheets as given by the theme or + :confval:`html_style`. + + .. versionadded:: 5.1 + +.. data:: title + + The title of the current document, as used in the ``<title>`` tag. + +.. data:: use_opensearch + + The value of :confval:`html_use_opensearch`. + +.. data:: version + + The value of :confval:`version`. + + +In addition to these values, there are also all **theme options** available +(prefixed by ``theme_``), as well as the values given by the user in +:confval:`html_context`. + +In documents that are created from source files (as opposed to +automatically-generated files like the module index, or documents that already +are in HTML form), these variables are also available: + +.. data:: body + + A string containing the content of the page in HTML form as produced by the + HTML builder, before the theme is applied. + +.. data:: display_toc + + A boolean that is True if the toc contains more than one entry. + +.. data:: meta + + Document metadata (a dictionary), see :ref:`metadata`. + +.. data:: metatags + + A string containing the page's HTML :dudir:`meta` tags. + +.. data:: next + + The next document for the navigation. This variable is either false or has + two attributes ``link`` and ``title``. The title contains HTML markup. For + example, to generate a link to the next page, you can use this snippet:: + + {% if next %} + <a href="{{ next.link|e }}">{{ next.title }}</a> + {% endif %} + +.. data:: page_source_suffix + + The suffix of the file that was rendered. Since we support a list of + :confval:`source_suffix`, this will allow you to properly link to the + original source file. + +.. data:: parents + + A list of parent documents for navigation, structured like the :data:`next` + item. + +.. data:: prev + + Like :data:`next`, but for the previous page. + +.. data:: sourcename + + The name of the copied source file for the current document. This is only + nonempty if the :confval:`html_copy_source` value is ``True``. + This has empty value on creating automatically-generated files. + +.. data:: toc + + The local table of contents for the current page, rendered as HTML bullet + lists. + +.. data:: toctree + + A callable yielding the global TOC tree containing the current page, rendered + as HTML bullet lists. Optional keyword arguments: + + ``collapse`` + If true, all TOC entries that are not ancestors of the current page are + collapsed. + ``True`` by default. + + ``maxdepth`` + The maximum depth of the tree. Set it to ``-1`` to allow unlimited depth. + Defaults to the max depth selected in the toctree directive. + + ``titles_only`` + If true, put only top-level document titles in the tree. + ``False`` by default. + + ``includehidden`` + If true, the ToC tree will also contain hidden entries. + ``False`` by default. |