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-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev