Excerpts from Dan Prince's message of 2015-04-13 14:07:28 -0700: > 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.
I agree Dan, which is why I'd like to make sure these are machine readable and consistent. I think it would actually make sense to make our argument isolation efforts utilize this format, as that would make sure that these are consistent with the code as well. __________________________________________________________________________ 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
