Documenting jinja templates¶
This contrib extension, jinja_autodoc, provides a Sphinx
domain for describing jinja templates.
This package is available on PyPI as jinja-autodoc.
In order to use it, add jinja_autodoc into
extensions list of your Sphinx configuration file (conf.py):
extensions = ['jinja_autodoc']
Basic usage¶
There are several provided directives that describe jinja templates.
.. jinja:template:: /etc/network/interfaces
Template for network config
:param hostname: your computer's hostname
:type hostname: str
:param ip: your computer's ip
:type ip: str
will be rendered as:
- TEMPLATE /etc/network/interfaces¶
Template for network config
- Parameters:
hostname (str) – your computer’s hostname
ip (str) – your computer’s ip
Automatic documentation¶
The autotemplate directive generates Jinja reference documentation from a start comment in jinja template.
Basicly it just takes docstring between {# and #} and inserts it where you
specified autotemplate directive.
To make everything work you also have to specify relative or absolute path
to your templates. If this option is not specified templates won’t be displayed
in your documentation.
You can do this by setting jinja_template_path in your Sphinx configuration
(conf.py) file.
For example, considering this template:
{#
This is a sample template
:param param1: This is sample input parameter to this template
:type param1: str
#}
the following documentation:
.. autotemplate:: sample_template.in
will be rendered as:
- TEMPLATE sample_template.in¶
This is a sample template
- Parameters:
param1 (str) – This is sample input parameter to this template
If the path is a directory, all the templates inside this directory will be rendered.
To restrict the discovery to a subset of files, you can use the jinja_template_pattern to set a pattern to recognize template filenames.
jinja_template_pattern = r"\.html$"
Directives¶
- .. jinja:template:: path¶
Describes an jinja template.
- .. jinja:autotemplate:: path¶
Reads the first comment of a file and dynamically builds a Jinja documentation. If the path is a directory, the templates in the directory will be documented.