Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix local extensions documentation #1686

Merged
merged 1 commit into from May 31, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
13 changes: 6 additions & 7 deletions docs/advanced/local_extensions.rst
Expand Up @@ -3,7 +3,7 @@
Local Extensions
----------------

*New in Cookiecutter X.x*
*New in Cookiecutter 2.1*

A template may extend the Cookiecutter environment with local extensions.
These can be part of the template itself, providing it with more sophisticated custom tags and filters.
Expand All @@ -18,13 +18,10 @@ To do so, a template author must specify the required extensions in ``cookiecutt
"_extensions": ["local_extensions.FoobarExtension"]
}

This example assumes that a ``local_extensions`` folder (python module) exists in the template root.
It will contain a ``main.py`` file, containing the following (for instance):
This example uses a simple module ``local_extensions.py`` which exists in the template root, containing the following (for instance):

.. code-block:: python

# -*- coding: utf-8 -*-

from jinja2.ext import Extension


Expand All @@ -48,8 +45,6 @@ It's likely that we'd only want to register a single function as a filter. For t

.. code-block:: python

# -*- coding: utf-8 -*-

from cookiecutter.utils import simple_filter


Expand All @@ -58,3 +53,7 @@ It's likely that we'd only want to register a single function as a filter. For t
return v * 2

This snippet will achieve the exact same result as the previous one.

For complex use cases, a python module ``local_extensions`` (a folder with an ``__init__.py``) can also be created in the template root.
Here, for example, a module ``main.py`` would have to export all extensions with ``from .main import FoobarExtension, simplefilterextension`` or ``from .main import *`` in the ``__init__.py``.