sphinx-jinja2-compat

0.4.1 · active · verified Mon Apr 13

sphinx-jinja2-compat, current version 0.4.1, is a utility library designed to patch Jinja2 v3, restoring compatibility with earlier Sphinx versions. It also addresses issues to ensure some Sphinx versions function correctly on Python 3.10. This library primarily serves as a compatibility layer to bridge gaps between major versions of its dependencies, rather than providing new user-facing features. Releases are made on an as-needed basis to address specific compatibility challenges.

Warnings

gotcha This library operates as a low-level patch and does not expose direct user-facing Python imports or functions for common usage. Its effect is passive, modifying the behavior of Jinja2 within Sphinx.
Fix: No fix needed; this is its intended mode of operation. Do not attempt to import `sphinx_jinja2_compat` into your `conf.py` or Python code for direct functionality.
breaking If your Sphinx project or custom extensions rely on specific Jinja2 v3 behaviors that `sphinx-jinja2-compat` alters to restore compatibility, unintended side effects might occur. This is more likely for highly customized Sphinx setups.
Fix: Test your Sphinx build thoroughly after installation. If issues arise, consider temporarily disabling the patches by setting the environment variable `NO_SPHINX_JINJA2_COMPAT=1` to isolate the problem. Adjust custom code to be compatible with the patched Jinja2 behavior if necessary.
gotcha The patches applied by `sphinx-jinja2-compat` can be disabled at runtime by setting the environment variable `NO_SPHINX_JINJA2_COMPAT` to `1` before running Sphinx. This might be useful for debugging or when the compatibility layer is not desired.
Fix: To disable the patches, ensure `os.environ['NO_SPHINX_JINJA2_COMPAT'] = '1'` is set in your build environment or a script wrapper before Sphinx execution. To re-enable, remove or unset the variable.

Install

pip install sphinx-jinja2-compat Install from PyPI

Quickstart

Installation of `sphinx-jinja2-compat` is typically sufficient; it works by applying patches on import of relevant modules within Sphinx, rather than requiring explicit inclusion in `conf.py`'s `extensions` list. The primary effect is restoring compatibility for older Sphinx versions with Jinja2 v3 and ensuring Python 3.10 compatibility for certain Sphinx versions. The patches can be disabled by setting the environment variable `NO_SPHINX_JINJA2_COMPAT` to `1`.

# Simply install the package. No direct code import or configuration in conf.py is typically needed.
# The patch is applied automatically upon import of related modules within Sphinx.
# To disable the patches, set the environment variable before running Sphinx:
import os
os.environ['NO_SPHINX_JINJA2_COMPAT'] = '1'
# Then run Sphinx as usual, e.g., via command line:
# sphinx-build -b html source build

print("sphinx-jinja2-compat is active once installed, patching Jinja2 for Sphinx compatibility.")

view raw JSON →