Sphinx Jinja

2.0.2 · active · verified Fri Apr 10

Sphinx Jinja is a Python library that enables the embedding of Jinja2 templates directly within Sphinx documentation. It allows dynamic content generation, variable injection, and custom logic using Jinja2 syntax in reStructuredText or MyST files. The current version is 2.0.2, and releases are generally made as needed, with significant changes between major versions.

Warnings

breaking The configuration parameters in `conf.py` for setting up Jinja2 environments, contexts, filters, globals, and tests have changed significantly in version 2.0.0.
Fix: Migrate your `conf.py` configuration from `jinja_contexts`, `jinja_env`, `jinja_filters`, `jinja_globals`, `jinja_tests` (pre-2.0.0) to the new style using `jinja_contexts`, `jinja_filters`, `jinja_globals`, `jinja_tests`, and `jinja_env_kwargs` (2.0.0+). Consult the official documentation for detailed migration guides.
breaking Version 2.0.0 dropped support for Python 3.6. It now requires Python 3.7 or newer.
Fix: Ensure your project is running on Python 3.7 or a later version before upgrading to sphinx-jinja 2.x.
breaking Version 2.0.0 tightened its dependency on Sphinx, requiring Sphinx 4.0.0 or newer.
Fix: Upgrade your Sphinx installation to version 4.0.0 or higher: `pip install 'sphinx>=4.0.0'`.
breaking Version 2.0.0 updated its dependency on Jinja2, requiring Jinja2 3.0.0 or newer.
Fix: Upgrade your Jinja2 installation to version 3.0.0 or higher: `pip install 'Jinja2>=3.0.0'`.

Install

pip install sphinx-jinja Install stable version

Imports

Extension Configuration
```
extensions = ['sphinx_jinja']
jinja_contexts = {...}
```
sphinx-jinja is typically integrated by adding 'sphinx_jinja' to the 'extensions' list in conf.py, not through direct Python imports of its internal components. Configuration is done via global variables in conf.py.

Quickstart

To get started, add 'sphinx_jinja' to your `extensions` list in `conf.py`. Then, configure Jinja contexts, filters, globals, and environment options using `jinja_contexts`, `jinja_filters`, `jinja_globals`, `jinja_tests`, and `jinja_env_kwargs` variables. Finally, use the `.. jinja::` directive in your reStructuredText or MyST files to render templates. The provided example shows a `conf.py` setup and a conceptual `.rst` usage.

# conf.py
project = 'My Jinja Project'
copyright = '2024, Your Name'
html_theme = 'alabaster'
extensions = [
    'sphinx_jinja'
]

jinja_contexts = {
    'global_vars': {
        'product_name': 'Awesome App',
        'version': '1.0.0'
    }
}

jinja_filters = {
    'upper': lambda s: s.upper()
}

jinja_env_kwargs = {
    'trim_blocks': True,
    'lstrip_blocks': True
}

# docs/index.rst
# .. jinja:: global_vars
#
#    Welcome to {{ product_name }} ({{ version }}).
#    This text will be uppercased: {{ "hello world" | upper }}

view raw JSON →