[openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements

Ben Nemec openstack at nemebean.com
Tue Apr 7 21:23:25 UTC 2015

+2 from me.  I'm still in favor of killing off most/all input env vars
and coming up with a less error-prone way to handle configuration, but
in the meantime this is a big step toward sanity for users.

On 04/07/2015 04:06 PM, Gregory Haynes wrote:
> 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?
> Cheers,
> Greg
> 1 - https://review.openstack.org/#/c/171320/
> 2 - http://docs-draft.openstack.org/20/171320/1/check/gate-diskimage-builder-docs/d3bdf04//doc/build/html/elements/apt-sources/README.html
> 3 - http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists
> 4 - http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

More information about the OpenStack-dev mailing list