search

cylc / cylc-doc

Documentation (User Guide, Cheat Sheets, etc.) for the Cylc Workflow Engine.
https://cylc.github.io/cylc-doc/
GNU General Public License v3.0
9 stars 19 forks source link

Explain code in flow.cylc files. #651

Closed hjoliver closed 5 months ago

hjoliver commented 1 year ago

Explain exactly what Jinja2 and shell code embedded in a flow.cylc means, and when/where it will be evaluated.

Requirements check-list

hjoliver commented 1 year ago

I fear the tone and length of this article makes Cylc seem limited and complex, which I don't think is right.

On re-reading it, I agree. I'll simplify and re-tone it!

The main takeaway points are: ... I would be tempted to convey these messages through a couple of notes or warnings in the Jinja2 section / tutorial.

It's worse than that though. It involves shell code as well as Jinja2.

Take this recent forum post:

https://cylc.discourse.group/t/how-do-you-use-a-variable-defined-in-environment-in-the-directives-section/760

and shortly after:

https://cylc.discourse.group/t/how-do-you-use-a-variable-defined-in-environment-in-the-directives-section/760/3

And, I see this sort of misunderstanding quite often.

hjoliver commented 1 year ago

OK thanks for the feedback. I've stripped that sucker back to the bare bones (I think). Try it now for size.

I'll add some cross-referencing if the content is agreed.

hjoliver commented 12 months ago

TODO: add cross-referencing.

oliver-sanders commented 11 months ago

(spellcheck doesn't like the word preprocessing, we can add it to src/dictionaries/words to fix this)