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

Smigiel, Dariusz dariusz.smigiel at intel.com
Wed Apr 8 09:30:21 UTC 2015


> 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

Looks very promising.
Are you planning to add some kind of lint[1] to RST and force formatting or based on common sense for all developers involved?
One minor thing: would be nice to have permalinks to Variables.

In general, it's more readable and understandable compared to previous version.
+1 from me :)

[1] https://pypi.python.org/pypi/restructuredtext_lint/0.4.0

--
Dariusz Smigiel
Intel Technology Poland



More information about the OpenStack-dev mailing list