Document order of execution of Jinja Expressions

[gilesknap]

This needs adding to the docs as an essential guide to how your yaml gets turned into runtime assets.

• ioc.yaml files have their entities loaded in the order they appear in the file
• first pass of rendering is for arguments and this applies to values supplied in ioc.yaml as well as defaults coming from the .support.yaml
  • argument values are interpreted in the order they appear in the file
  • Jinja expressions are allowed in string args (todo we would like to support jinja string | other_type unions).
  • The jinja context for argument rendering contains all the other arguments of the current entity.
  • An argument may therfore forward or backward reference other arguments
  • However only backward references will have any Jinja rendering already done
  • Note that a Jinja expression with (backward only) reference to another entity (using its id) will become a dataclass of the object's args (for complicated reasons it is not an actual Entity class - but the behaviour is nearly identical)
• Once all Entity have been read in, we then render the pre_init and post_init using Jina
  • The order is again top to bottom of the file
  • The jinja context contains a dictionary of Entity classes indexed by their id (entities that have no id are not available to Jinja at this stage)

That's it! (phew!). Although this reads as complicated it is essentially just saying everything happens top to bottom of the yaml.

UPDATE: Caveat: Values are always evalutated after Args - this might be an issue. Maybe we need a PreValues and a PostValues to support the Technosoft axis number field??

[GDYendell]

entities that have no id are not available to Jinja at this stage

What defines whether an Entity has an id or not?

[gilesknap]

entities that have no id are not available to Jinja at this stage

What defines whether an Entity has an id or not?

You define an id with an Arg like this:

• type: id
  name:myID
  description: the name of this object

You only need to make an ID if you want to refer to the thing from another entity.

[GDYendell]

I think that is going to be a common point of confusion, so should have a very clear explanation and maybe some examples of defining and referencing

[gilesknap]

Jinja rendering of parameters / defines now all happens in the Entity model validator during IOC instance deserialisation.

https://github.com/epics-containers/ibek/blob/list-arg2dict-param/src/ibek/ioc.py#L97-L122

The second phase of jinja rendering of pre_init, post_init, databases happens in ioc_commands.generate.

I have a good handle on the order of jinja rendering and it is relatively intuitive. Just need to write it up.