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

Gregory Haynes greg at greghaynes.net
Tue Apr 7 21:06:52 UTC 2015


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.



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

More information about the OpenStack-dev mailing list