2008-03-09 16:32:24 -05:00
|
|
|
.. _templating:
|
|
|
|
|
|
|
|
|
|
Templating
|
|
|
|
|
==========
|
2008-03-12 16:37:22 -05:00
|
|
|
|
2008-03-22 08:14:00 -05:00
|
|
|
Sphinx uses the `Jinja <http://jinja.pocoo.org>`_ templating engine for its HTML
|
2008-03-12 16:37:22 -05:00
|
|
|
templates. Jinja is a text-based engine, and 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.
|
|
|
|
|
|
2008-03-25 14:20:26 -05:00
|
|
|
|
|
|
|
|
Do I need to use Sphinx' templates to produce HTML?
|
|
|
|
|
---------------------------------------------------
|
|
|
|
|
|
|
|
|
|
No. You have several other options:
|
|
|
|
|
|
2008-04-13 13:16:55 -05:00
|
|
|
* 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.
|
|
|
|
|
|
2008-03-25 14:20:26 -05:00
|
|
|
* You can :ref:`write a custom builder <writing-builders>` that derives from
|
|
|
|
|
:class:`~sphinx.builder.StandaloneHTMLBuilder` and calls your template engine
|
|
|
|
|
of choice.
|
|
|
|
|
|
|
|
|
|
* You can use the :class:`~sphinx.builder.PickleHTMLBuilder` that produces
|
|
|
|
|
pickle files with the page contents, and postprocess them using a custom tool,
|
|
|
|
|
or use them in your Web application.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Jinja/Sphinx Templating Primer
|
|
|
|
|
------------------------------
|
|
|
|
|
|
2008-04-27 09:23:11 -05:00
|
|
|
The default templating language in Sphinx is Jinja. It's Django/Smarty inspired
|
2008-04-27 11:35:55 -05:00
|
|
|
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.
|
2008-03-12 16:37:22 -05:00
|
|
|
|
2008-04-27 09:23:11 -05:00
|
|
|
To customize the output of your documentation you can override all the templates
|
2008-04-27 11:35:55 -05:00
|
|
|
(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 folder the
|
|
|
|
|
Sphinx quickstart generated for you.
|
2008-03-12 16:37:22 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
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 builtin templates that come with Sphinx.
|
2008-03-12 16:37:22 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
A template contains **variables**, which are replaced with values when the
|
2008-04-27 09:23:11 -05:00
|
|
|
template is evaluated, **tags**, which control the logic of the template and
|
|
|
|
|
**blocks** which are used for template inheritance.
|
2008-04-13 13:16:55 -05:00
|
|
|
|
2008-04-27 09:23:11 -05:00
|
|
|
Sphinx provides base templates with a couple of blocks it will fill with data.
|
2008-04-27 11:35:55 -05:00
|
|
|
The default templates are located in the :file:`templates` folder of the Sphinx
|
2008-04-27 09:23:11 -05:00
|
|
|
installation directory. Templates with the same name in the
|
2008-04-27 11:35:55 -05:00
|
|
|
:confval:`templates_path` override templates located in the builtin folder.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
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:
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
|
|
|
|
|
|
{% extends "!layout.html" %}
|
|
|
|
|
{% block rootrellink %}
|
|
|
|
|
<li><a href="http://project.invalid/">Project Homepage</a> »</li>
|
|
|
|
|
{{ super() }}
|
|
|
|
|
{% endblock %}
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
By prefixing the name of the extended template with an exclamation mark, Sphinx
|
|
|
|
|
will load the builtin layout template. If you override a block, you should call
|
|
|
|
|
``{{ super() }}`` somewhere to render the block's content in the extended
|
|
|
|
|
template -- unless you don't want that content to show up.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Blocks
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
The following blocks exist in the ``layout`` template:
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
`doctype`
|
2008-04-27 11:35:55 -05:00
|
|
|
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.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-09-24 06:48:43 -05:00
|
|
|
`linktags`
|
2008-04-27 11:35:55 -05:00
|
|
|
This block adds a couple of ``<link>`` tags to the head section of the
|
2008-04-27 09:23:11 -05:00
|
|
|
template.
|
|
|
|
|
|
|
|
|
|
`extrahead`
|
2008-04-27 11:35:55 -05:00
|
|
|
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.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
`relbar1` / `relbar2`
|
2008-04-27 11:35:55 -05:00
|
|
|
This block contains 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 %}
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
`rootrellink` / `relbaritems`
|
2008-04-27 11:35:55 -05:00
|
|
|
Inside the relbar there are three sections: The `rootrellink`, the links
|
2008-09-24 06:48:43 -05:00
|
|
|
from the documentation and the custom `relbaritems`. The `rootrellink` is a
|
|
|
|
|
block that by default contains a list item pointing to the master 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`.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
`document`
|
|
|
|
|
The contents of the document itself.
|
|
|
|
|
|
|
|
|
|
`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
|
2008-04-27 11:35:55 -05:00
|
|
|
default sidebar. If you want to swap the sidebar location override this and
|
|
|
|
|
call the `sidebar` helper:
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
|
|
|
|
|
|
{% block sidebar1 %}{{ sidebar() }}{% endblock %}
|
|
|
|
|
{% block sidebar2 %}{% endblock %}
|
|
|
|
|
|
2008-04-27 13:10:48 -05:00
|
|
|
(The `sidebar2` location for the sidebar is needed by the ``sphinxdoc.css``
|
2008-04-27 11:35:55 -05:00
|
|
|
stylesheet, for example.)
|
|
|
|
|
|
2008-04-27 14:43:45 -05:00
|
|
|
`sidebarlogo`
|
|
|
|
|
The logo location within the sidebar. Override this if you want to place
|
|
|
|
|
some content at the top of the sidebar.
|
|
|
|
|
|
|
|
|
|
`sidebartoc`
|
|
|
|
|
The table of contents within the sidebar.
|
|
|
|
|
|
|
|
|
|
`sidebarrel`
|
|
|
|
|
The relation links (previous, next document) within the sidebar.
|
|
|
|
|
|
|
|
|
|
`sidebarsearch`
|
|
|
|
|
The search box within the sidebar. Override this if you want to place some
|
|
|
|
|
content at the bottom of the sidebar.
|
|
|
|
|
|
2008-04-27 09:23:11 -05:00
|
|
|
`footer`
|
|
|
|
|
The block for the footer div. If you want a custom footer or markup before
|
|
|
|
|
or after it, override this one.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Configuration Variables
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Inside templates you can set a couple of variables used by the layout template
|
|
|
|
|
using the ``{% set %}`` tag:
|
|
|
|
|
|
|
|
|
|
.. data:: reldelim1
|
2008-04-27 11:35:55 -05:00
|
|
|
|
|
|
|
|
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.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. data:: reldelim2
|
2008-04-27 11:35:55 -05:00
|
|
|
|
|
|
|
|
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.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
Overriding works like this:
|
|
|
|
|
|
|
|
|
|
.. sourcecode:: html+jinja
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
{% extends "!layout.html" %}
|
|
|
|
|
{% set reldelim1 = ' >' %}
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Helper Functions
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
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)
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
Return the path to a Sphinx document as a URL. Use this to refer to built
|
|
|
|
|
documents.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
.. function:: pathto(file, 1)
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
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.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
.. function:: hasdoc(document)
|
|
|
|
|
|
|
|
|
|
Check if a document with the name *document* exists.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. function:: sidebar()
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
Return the rendered sidebar.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. function:: relbar()
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
Return the rendered relbar.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Global Variables
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
These global variables are available in every template and are safe to use.
|
2008-04-27 11:35:55 -05:00
|
|
|
There are more, but most of them are an implementation detail and might change
|
|
|
|
|
in the future.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. data:: docstitle
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
The title of the documentation (the value of :confval:`html_title`).
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. data:: sourcename
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
The name of the copied source file for the current document. This is only
|
|
|
|
|
nonempty if the :confval:`html_copy_source` value is true.
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. data:: builder
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
The name of the builder (for builtin builders, ``html``, ``htmlhelp``, or
|
|
|
|
|
``web``).
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. data:: next
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
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:
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
.. sourcecode:: html+jinja
|
2008-04-27 09:23:11 -05:00
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
{% if next %}
|
|
|
|
|
<a href="{{ next.link|e }}">{{ next.title }}</a>
|
|
|
|
|
{% endif %}
|
2008-04-27 09:23:11 -05:00
|
|
|
|
|
|
|
|
.. data:: prev
|
|
|
|
|
|
2008-04-27 11:35:55 -05:00
|
|
|
Like :data:`next`, but for the previous page.
|
