1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
.. image:: https://github.com/tardyp/sphinx-jinja/actions/workflows/ci.yml/badge.svg
sphinx-jinja
============
A sphinx extension to include jinja based templates based documentation into a sphinx doc
Usage
=====
In your rst doc, you can use the following snippet to use a jinja template to generate your doc
.. code:: rst
.. jinja:: first_ctx
{% for k, v in topics.items() %}
{{k}}
~~~~~
{{v}}
{% endfor %}
In your sphinx ``conf.py`` file, you can create or load the contexts needed for your jinja templates
.. code:: python
extensions = ['sphinx_jinja']
jinja_contexts = {
'first_ctx': {'topics': {'a': 'b', 'c': 'd'}}
}
You can also customize the jinja ``Environment`` by passing custom kwargs, adding filters, tests, and globals, and setting policies:
.. code:: python
jinja_env_kwargs = {
'lstrip_blocks': True,
}
jinja_filters = {
'bold': lambda value: f'**{value}**',
}
jinja_tests = {
'instanceof': lambda value, type: isinstance(value, type),
}
jinja_globals = {
'list': list,
}
jinja_policies = {
'compiler.ascii_str': False,
}
Which can then be used in the templates:
.. code:: rst
Lists
-----
{% for o in objects -%}
{%- if o is instanceof list -%}
{%- for x in o -%}
- {{ x|bold }}
{% endfor -%}
{%- endif -%}
{%- endfor %}
Available options
=================
- ``file``: allow to specify a path to Jinja instead of writing it into the content of the
directive. Path is relative to the current directory of sphinx-build tool, typically the directory
where the ``conf.py`` file is located.
- ``header_char``: character to use for the the headers. You can use it in your template to set your
own title character:
For example:
.. code:: rst
Title
{{ options.header_char * 5 }}
- ``header_update_levels``: If set, a header in the template will appear as the same level as a
header of the same style in the source document, equivalent to when you use the ``include``
directive. If not set, headers from the template will be in levels below whatever level is active
in the source document.
- ``debug``: print debugging information during sphinx-build. This allows you to see the generated
rst before sphinx builds it into another format.
Example of declaration in your RST file:
.. code:: rst
.. jinja:: approval_checks_api
:file: relative/path/to/template.jinja
:header_char: -
Each element of the ``jinja_contexts`` dictionary is a context dict for use in your jinja templates.
Running tests
=============
* pip install tox
* tox
|
