sphinx-jinja2#

A sphinx extension to add the jinja directive, for rendering jinja templates.

Note

This is an adaption of sphinx-jinja, which appears to be unmaintained.

Usage#

Simply install and add sphinx_jinja2 to your conf.py extensions list.

pip install sphinx-jinja2

extensions = [
    ...
    'sphinx_jinja2',
    ...
]

Guide#

The most basic usage is to render an inline template using the jinja directive, where the ctx option is a JSON dict that will be passed to the template as the context:

Example 1

.. jinja::
    :ctx: {"name": "World"}

    Hallo {{ name }}!

Hallo World!

The Sphinx environment is also available by default as env:

Example 2

.. jinja::

    This is {{ env.config.project }} version {{ env.config.version }}.

This is sphinx-jinja2 version 0.0.1.

To set globally available variables, use the jinja2_contexts option in your conf.py, and refer to them by name as the first argument to the jinja directive:

Example 3

conf.py:

jinja2_contexts = {"ctx1": {"name": "World"}}

.. jinja:: ctx1

    Hallo {{ name }}!

Hallo World!

Templates from files#

To load a template from a file, use the file option. Similar to the include directive, the path is relative to the source file that contains the directive, or relative to the source directory if the path starts with /. The file should always be encoded in UTF-8. If these files change then Sphinx will re-build pages that use them!

Example 4

templates/example1.jinja:

Hallo {{ name }}!

.. jinja::
    :file: templates/example1.jinja
    :ctx: {"name": "World"}

Hallo World!

Templates can include or extend other templates. Referenced templates are always relative to the source directory, and Sphinx will also correctly re-build pages that use them.

Example 5

templates/example1.jinja:

Hallo {{ name }}!

.. jinja::
    :ctx: {"name": "World", "more": "content"}

    {% include "templates/example1.jinja" %}

    More {{ more }}!

Hallo World!

Headings in templates#

Rendered templates are parsed within the context of the current document, and so heading levels are relative to the current document.

Example 6

.. jinja::

    Sub-heading
    ...........

    Content

Sub-heading#

Content

If you need a generic template containing a heading, then perhaps use a context variable to specify the heading character:

Example 7

.. jinja::
    :ctx: {"heading_char": "."}

    Sub-heading
    {{ heading_char * 11 }}

    Content

Sub-heading#

Content

Debugging#

To see the rendered templates in the built documentation, use the debug option for a single directive, or the jinja2_debug option in your conf.py to enable it globally:

Example 8

.. jinja::
    :ctx: {"name": "World"}
    :debug:

    Hallo **{{ name }}**!

Hallo **World**!

Hallo World!

Warning messages#

Warning messages are displayed in the Sphinx build output, for problematic inputs, these all have the type jinja2, which can be used to suppress them in the Sphinx configuration:

suppress_warnings = ["jinja2"]

Since is difficult / impossible to map the source line numbers, from the template to the Jinja rendered content, problems with the parsing of the rendered content always refer to the first line number either of the jinja directive, or the template file (when using the file option).

Configuration#

The following global configuration variables are available:

Configuration Options

jinja2_contexts:: A mapping of context names to context variables (default: {})
jinja2_env_kwargs:: Keyword arguments passed to jinja2.Environment (default: {})
jinja2_filters:: A mapping of filter names to filter functions (see https://jinja.palletsprojects.com/en/3.1.x/api/#writing-filters) (default: {})
jinja2_tests:: A mapping of test names to test functions (see https://jinja.palletsprojects.com/en/3.1.x/api/#writing-tests) (default: {})
jinja2_debug:: Output the rendered template (default: False)