Open Stack

Excerpts from Gregory Haynes's message of 2015-04-07 14:06:52 -0700:
> Hello,
> 
> Id like to propse a standard for consistently documenting our
> diskimage-builder elements. I have pushed a review which transforms the
> apt-sources element to this format[1][2]. Essentially, id like to move
> in the direction of making all our element README.rst's contain a sub
> section called Environment Vairables with a Definition List[3] where
> each entry is the environment variable. Under that environment variable
> we will have a field list[4] with Required, Default, Description, and
> optionally Example.
> 
> The goal here is that rather than users being presented with a wall of
> text that they need to dig through to remember the name of a variable,
> there is a quick way for them to get the information they need. It also
> should help us to remember to document the vital bits of information for
> each vairable we use.
> 
> Thoughts?

I discussed a format for something similar here:

https://review.openstack.org/#/c/162267/

Perhaps we could merge the effort.

The design and implementation in that might take some time, but if we
can document the variables at the same time we prepare the inputs for
isolation, that seems like a winning path forward.