IntenseWebs/sphinx
3
0 Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2026-11-02 09:00:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Improve landing page (#12453)

Browse Source 
This commit is intended to improve new user's first-interaction with the Sphinx site:

- Make page header icon/text smaller and not capitalized
- Give min-width to left sidebar (it was getting too small at certain window sizes)
- Replace features list on landing page with admonition boxes, with adaptive layout
- Add landing page "used by" section
- Slightly restructure the Extension section, into Tutorials and How-tos
- Add code to `conf.py` to write HTML write redirect pages for moved documents
- Improve support page, by adding link to Stackoverflow, GH discussion and ReadtheDocs,
  and remove defunct link to libera chat and matplotlib tutorial
This commit is contained in:
Chris Sewell authored and GitHub committed 2024-06-21 20:12:57 +02:00
1 parent bc1a5c5c88
commit 8f97fd276a
22 files changed
+271 -97
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

doc/development/html_themes/index.rst
+456
View File
@@ -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:
.. sourcecode:: 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.
doc/development/html_themes/templating.rst
+479
View File
@@ -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> &raquo;</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 ``' &raquo;'`` 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 = ' &gt;' %}
.. 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 reST 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 reST 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.