Document formatter and available paths

[atward]

A large part of user confusion is coming from not knowing what keys/paths are available for the {} config syntax. Recommend documenting a list of what is available, and any additional keys that are derived/appended.

• account_id
• config_root
• environment
• environments..*
• region
• stacks..*
• tags.*
• vars.*

Additionally::

• __stack_name__
• __environment__ (ie: environments.environment)
• __stack__ (ie: stacks.__stack_name__)
• _key_name_X syntax

Formatters:

• overview/syntax
• :env - '${ENV_VAR}'
• :date - date object from string
• :underscored- '-' to '_'
• :config_dir - dirname of the bespin.yml the config option was defined in (NOTE: python2.7+ only)

environment variables

• declaring before using
• env
• build_env
• stack_name_env

variables (ie: XXX_var_XXX)

• how this works
• why it's needed
• parts of the config where this is valid (params_yaml only?)

[delfick]

you also have these three inside the block for each stack https://github.com/delfick/bespin/blob/master/bespin/collector.py#L187-L189

There is some effort to talk about variables in https://github.com/delfick/bespin/blob/master/docs/docs/stacks.rst#defining-variables but I'm sure it could do with improvement

[delfick]

the _key_name_X syntax comes from the sb.formatted spec.

https://github.com/delfick/input_algorithms/blob/master/input_algorithms/spec_base.py#L1081

Which uses https://github.com/delfick/input_algorithms/blob/master/input_algorithms/meta.py#L76

[atward]

PR #61 addresses first half (formatter). Need to add more explanation around 2nd pass/variable resolution in stacks.rst