From 3105b46afa8088670160f4f68e4a5de270c59741 Mon Sep 17 00:00:00 2001
From: Vinay P <mail@vinayvinay.com>
Date: Thu, 18 Mar 2021 12:19:28 +0000
Subject: [PATCH] Document use of Jinja2 extensions with fetch:cookiecutter

Signed-off-by: Vinay P <mail@vinayvinay.com>
---
 .../Dockerfile                                | 11 ++++
 .../README.md                                 | 63 +++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 contrib/docker/cookiecutter-with-jinja2-extensions/Dockerfile
 create mode 100644 contrib/docker/cookiecutter-with-jinja2-extensions/README.md

diff --git a/contrib/docker/cookiecutter-with-jinja2-extensions/Dockerfile b/contrib/docker/cookiecutter-with-jinja2-extensions/Dockerfile
new file mode 100644
index 0000000000..4f5f72bdf8
--- /dev/null
+++ b/contrib/docker/cookiecutter-with-jinja2-extensions/Dockerfile
@@ -0,0 +1,11 @@
+FROM alpine:3.7
+
+RUN apk add --update \
+	git \
+	python \
+	python-dev \
+	py-pip \
+	g++ && \
+	pip install cookiecutter jinja2_custom_filters_extension && \
+	apk del g++ py-pip python-dev && \
+	rm -rf /var/cache/apk/*
diff --git a/contrib/docker/cookiecutter-with-jinja2-extensions/README.md b/contrib/docker/cookiecutter-with-jinja2-extensions/README.md
new file mode 100644
index 0000000000..6b990f77a3
--- /dev/null
+++ b/contrib/docker/cookiecutter-with-jinja2-extensions/README.md
@@ -0,0 +1,63 @@
+# Using Cookiecutter with Jinja2 extensions
+
+Jinja2 extensions can be used with the scaffolder's `fetch:cookiecutter` built-in action to add filters, tests, or to extend the parser.
+
+Using Cookiecutter extensions is a two-step process:
+
+- [Installing the extension](#installing-the-extension), and
+- [Instructing Cookiecutter to use the extension](#instructing-cookiecutter-to-use-the-extension)
+
+### Installing the extension
+
+This step depends on how the scaffolder is setup to use Cookiecutter:
+
+- Using a local Cookiecutter, or
+- Using a Cookiecutter Docker image, e.g. [spotify/backstage-cookiecutter](https://github.com/backstage/backstage/blob/37e35b91/plugins/scaffolder-backend/scripts/Cookiecutter.dockerfile).
+
+Say we want to install [`jinja2_custom_filters_extension`](https://pypi.org/project/jinja2-custom-filters-extension/) to use the `upper_case_first_letter` filter in a Cookiecutter template.
+
+#### Using a local Cookiecutter
+
+The scaffolder is able to execute a locally installed Cookiecutter, and doesn't pull a Docker image in that case. If that's your setup, just ensure that the Jinja2 extensions, available via `pip` are installed alongside Cookiecutter, e.g. if Cookiecutter is baked into a custom Backstage image using `pip` and a `requirements.txt`:
+
+In the custom Backstage Dockerfile:
+
+```Dockerfile
+...
+RUN pip3 install -r requirements.txt
+...
+```
+
+In requirements.txt:
+
+```python
+...
+cookiecutter==1.7.2
+jinja2_custom_filters_extension==0.0.2
+...
+```
+
+#### Using a Cookiecutter Docker image
+
+If the scaffolder doesn't find a local Cookiecutter, it pulls down the `spotify/backstage-cookiecutter` image. You can create a custom Cookiecutter image based on that, install extensions into it, and use that instead. See for example, the [`Dockerfile`](./Dockerfile) in this directory.
+
+**Note:** The [`imageName`](https://github.com/vinayvinay/backstage/blob/37e35b91/plugins/scaffolder-backend/src/scaffolder/stages/templater/cookiecutter.ts#L77) that gets pulled isn't currently configurable. So, for the time being, you might have to customise the `scaffolder-backend` plugin to fetch your customised Cookiecutter Docker image.
+
+### Instructing Cookiecutter to use the extension
+
+Cookiecutter enables extensions mentioned in `cookiecutter.json`. `fetch:cookiecutter` generates a `cookiecutter.json`, deriving its values from `inputs` to `fetch:cookiecutter` in the scaffolder [Template](https://backstage.io/docs/features/software-templates/writing-templates), as:
+
+```yaml
+steps:
+  - id: fetch-base
+    name: Fetch Base
+    action: fetch:cookiecutter
+    input:
+      extensions:
+        - jinja2_custom_filters_extension.string_filters_extension.StringFilterExtension
+      url: https://github.com/spotify/cookiecutter-golang
+      values:
+        name: '{{ parameters.name }}'
+```
+
+Cookiecutter enables a few extensions by default. See the official Cookiecutter documentation for [Template Extensions](https://cookiecutter.readthedocs.io/en/1.7.2/advanced/template_extensions.html) for a list of such extensions, and more information.