> 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