> 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. >
As already suggested in my previous email [1], we could consider rest_lint [2] [1] http://lists.openstack.org/pipermail/openstack-dev/2015-April/060907.html [2] https://pypi.python.org/pypi/restructuredtext_lint/0.4.0 Any thoughts? -- Dariusz Smigiel Intel Technology Poland __________________________________________________________________________ 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
