document "magic" objects such as __salt__

[SEJeff]

This issue is two-fold. We need to document the special objects available in state files for users (such as salt, grains, etc) and the ones available inside of modules or state python modules such as __salt__, _opts_, _env_, etc.

The ability to reference grains via grains['os'] or invoke salt modules via salt['user.info]('foouser') in a state file is very powerful and should be well documented.

[thatch45]

I agree, thanks!
I think that doing a full docs sweep for 1.0.0 will be wise

[SEJeff]

It was dcolish's idea, but it does need to be done.

[whiteinge]

There's scattered documentation nowadays but I think this could still use some focus. Adding to the documentation sprint focus...

Refs #12446.

[whiteinge]

Quick checklist:

• Execution modules & State modules function-level injected variables: __salt__, __grains__, __opts__, __pillar__, __env__.
• Execution module magic module-level functions and vars: __virtual__(), __virtualname__, __init__().
• Available Jinja context in States: salt, grains, pillar, opts, env, sls.
• Available Jinja context in file.managed templated files: (all the args in the actual file.managed state itself).
• Available Jinja context in Reactor files: data.
• Magic variables in State modules: __running__, __low__, __lowstate__, __context__.
• Injected variables in runner modules: __opts__ (master opts).

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

If this issue is closed prematurely, please leave a comment and we will gladly reopen the issue.