Improving developer experience or docs for adding Jinja filters

The UX around testing new custom Jinja filters isn’t great. Part of this is that the documentation doesn't seem to have a section (if this is discussed elsewhere, please let me know) that addresses how filters are installed and loaded.

At first I tried my usual dev setup based on launchdev.sh - which works, but TMK mistral doesn’t get set up with that, and I need to be able to test in workflows.

So, trying with a “real” install means I have to modify files like /opt/stackstorm/st2/lib/python2.7/site-packages/st2common/util/jinja.py which is doable, but when I did this, those changes didn't seem to have any effect. I got this message:

JinjaEvaluationException: Can not evaluate Jinja expression [expression= escape_str | json_escape , error=no filter named 'json_escape', data={}]

No matter what I tried, I could not use this new filter in a Mistral workflow. I even restarted the VM and tried again, still no joy. It seems that Mistral is informed of all possible filters at some point, but it's obviously not anything I tried because this went nowhere.

At @armab suggestion, I tried an ActionChain instead, and that finally worked, though as I discovered, my succeeding changes to the filter code would only be recognized when I restarted StackStorm.

So to get StackStorm to recognize my new filter, I had to use ActionChains instead of a Mistral workflow, and I also have to restart StackStorm with sudo st2ctl restart (or presumably just restarting the component that loads these filters, haven't tried narrowing it down yet).

IMO, at a minimum, the following has to be confirmed and then communicated clearly in docs:

• Testing new filters cannot be done in mistral. If you want to test filters in a workflow, it has to be actionchains
• In order to let stackstorm reflect changes you made, you need to restart things with sudo st2ctl restart
• files to be aware of on an install (the docs talk about where it is in the repo but not where they are on the FS. This was easy for me to find but maybe not for others. Worth a quick note.)

Once the docs are updated, it may be worth going beyond this "current state" by supporting filter changes in mistral workflows, and adding jinja filters to st2ctl reload - but that's more dependent on how frequently users add their own filters. Like I said, the bare minimum (which may be good enough for now) is to add a section to the docs like "installing custom filters" that explains these caveats.

Start with the Jinja filters documentation section linked in the issue, then inspect launchdev.sh and st2common/util/jinja.py alongside the reported Mistral and ActionChain behavior. Confirm how custom filters are installed, loaded, and refreshed, including the relevant filesystem locations and st2ctl restart requirement. Done means the documented workflow and caveats are accurate and reproducible.