Open Stack

On Tue, 2015-04-07 at 21:06 +0000, 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?

I like the direction of the cleanup. +2

I do wonder who we'll enforce consistency in making sure future changes
adhere to the new format. It would be nice to have a CI check on these
things so people don't constantly need to debate the correct syntax,
etc.

Dan

> 
> 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