.. 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
Raw data
{
"_id": null,
"home_page": "https://github.com/tardyp/sphinx-jinja",
"name": "sphinx-jinja",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4",
"maintainer_email": "",
"keywords": "sphinx,jinja",
"author": "Pierre Tardy",
"author_email": "tardyp@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ea/90/7cf0e91aadcb5b3ff4796acbaf2c7887a55434df360914af9fc067c753c1/sphinx-jinja-2.0.2.tar.gz",
"platform": null,
"description": "\n.. image:: https://github.com/tardyp/sphinx-jinja/actions/workflows/ci.yml/badge.svg\n\nsphinx-jinja\n============\n\nA sphinx extension to include jinja based templates based documentation into a sphinx doc\n\nUsage\n=====\n\nIn your rst doc, you can use the following snippet to use a jinja template to generate your doc\n\n.. code:: rst\n\n .. jinja:: first_ctx\n\n {% for k, v in topics.items() %}\n\n {{k}}\n ~~~~~\n {{v}}\n {% endfor %}\n\nIn your sphinx ``conf.py`` file, you can create or load the contexts needed for your jinja templates\n\n.. code:: python\n\n extensions = ['sphinx_jinja']\n\n jinja_contexts = {\n 'first_ctx': {'topics': {'a': 'b', 'c': 'd'}}\n }\n\nYou can also customize the jinja ``Environment`` by passing custom kwargs, adding filters, tests, and globals, and setting policies:\n\n.. code:: python\n\n jinja_env_kwargs = {\n 'lstrip_blocks': True,\n }\n\n jinja_filters = {\n 'bold': lambda value: f'**{value}**',\n }\n\n jinja_tests = {\n 'instanceof': lambda value, type: isinstance(value, type),\n }\n\n jinja_globals = {\n 'list': list,\n }\n\n jinja_policies = {\n 'compiler.ascii_str': False,\n }\n\nWhich can then be used in the templates:\n\n.. code:: rst\n\n Lists\n -----\n\n {% for o in objects -%}\n {%- if o is instanceof list -%}\n {%- for x in o -%}\n - {{ x|bold }}\n {% endfor -%}\n {%- endif -%}\n {%- endfor %}\n\n\nAvailable options\n=================\n\n- ``file``: allow to specify a path to Jinja instead of writing it into the content of the\n directive. Path is relative to the current directory of sphinx-build tool, typically the directory\n where the ``conf.py`` file is located.\n\n- ``header_char``: character to use for the the headers. You can use it in your template to set your\n own title character:\n\n For example:\n\n .. code:: rst\n\n Title\n {{ options.header_char * 5 }}\n\n- ``header_update_levels``: If set, a header in the template will appear as the same level as a\n header of the same style in the source document, equivalent to when you use the ``include``\n directive. If not set, headers from the template will be in levels below whatever level is active\n in the source document.\n\n- ``debug``: print debugging information during sphinx-build. This allows you to see the generated\n rst before sphinx builds it into another format.\n\nExample of declaration in your RST file:\n\n.. code:: rst\n\n .. jinja:: approval_checks_api\n :file: relative/path/to/template.jinja\n :header_char: -\n\nEach element of the ``jinja_contexts`` dictionary is a context dict for use in your jinja templates.\n\n\nRunning tests\n=============\n\n* pip install tox\n* tox\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "includes jinja templates in a documentation",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/tardyp/sphinx-jinja",
"Repository": "https://github.com/tardyp/sphinx-jinja"
},
"split_keywords": [
"sphinx",
"jinja"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "209f81fe50b1861bda8c02b4272a166d14455411e04865ddaf3616f25d12cd50",
"md5": "d01647f0201b41bc5953fbbb84495f91",
"sha256": "705ebeb9b7a6018ca3f93724315a7c1effa6ba3db44d630e7eaaa15e4ac081a8"
},
"downloads": -1,
"filename": "sphinx_jinja-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d01647f0201b41bc5953fbbb84495f91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4",
"size": 4355,
"upload_time": "2022-07-05T11:57:47",
"upload_time_iso_8601": "2022-07-05T11:57:47.861080Z",
"url": "https://files.pythonhosted.org/packages/20/9f/81fe50b1861bda8c02b4272a166d14455411e04865ddaf3616f25d12cd50/sphinx_jinja-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea907cf0e91aadcb5b3ff4796acbaf2c7887a55434df360914af9fc067c753c1",
"md5": "5b824bceda6785f8449195ab59063120",
"sha256": "c6232b59a894139770be1dc6d0b00a379e4288ce78157904e1f8473dea3e0718"
},
"downloads": -1,
"filename": "sphinx-jinja-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5b824bceda6785f8449195ab59063120",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4",
"size": 4587,
"upload_time": "2022-07-05T11:57:49",
"upload_time_iso_8601": "2022-07-05T11:57:49.579876Z",
"url": "https://files.pythonhosted.org/packages/ea/90/7cf0e91aadcb5b3ff4796acbaf2c7887a55434df360914af9fc067c753c1/sphinx-jinja-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-07-05 11:57:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tardyp",
"github_project": "sphinx-jinja",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-jinja"
}
JSON
