Document `j2_environment` `autoescape` setting to control Jinja2 escaping about sceptre HOT 4 OPEN

Hey @iainelder, I think we'd all be happy to review a PR that clarifies our docs on this subject. I'd say put up a draft and we can engage with you about wording from there.

from sceptre.

These examples aren't helping me much, although I would welcome them as a PR that adds unit tests that illustrate the confusing behaviour. I did follow the links to @zaro0508 's comment here
https://github.com/orgs/Sceptre/discussions/1238#discussioncomment-2891480

Probably we also just need to make it clearer in the docs that there might be scenarios where you want to add

j2_environment:
   autoescape: False

?

from sceptre.

Probably we also just need to make it clearer in the docs

In the v4.3.0 docs the StackGroup Config page has the only discussion of j2_environment. It doesn't mention autoescape at all.

I think Jinja2 templates deserve their own page. That seems like the right place to detail the j2_environment setting and give enough examples to make it clear. One of the examples should show where you would want to control the autoescape setting, We need to call all out any gotchas such as the different default behaviors of the file and http template types.

These examples aren't helping me much

I'll grant that the output from the examples isn't clear without reading the code. The point there was to have a way to reproduce the behavior and to rule out possible PEBKAC errors and check my own understanding. Some of them might be helpful in the documentation, and the rest can be thrown away.

I would welcome them as a PR that adds unit tests that illustrate the confusing behaviour

I wouldn't bother yet. Only a developer would think to look there. The main problem here is a general lack of documentation on the Jinja2 templating feature.

I think there's a bug in here somewhere, but the behavior might be deliberate. I'd like to understand the spec before nailing things down with tests.

from sceptre.

@iainelder What kind of docs do you propose in this project that do not overlap with what is already documented in https://jinja.palletsprojects.com/en/3.1.x/

Compare the Jinja2 docs in Ansible
https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_templating.html

It largely just redirects you to the official Jinja2 docs. I think that's similar here?
https://docs.sceptre-project.org/dev/docs/templates.html

from sceptre.