[openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
dariusz.smigiel at intel.com
Wed Apr 15 07:29:45 UTC 2015
> 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. 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 where each entry is the environment variable. Under that
> > > environment variable we will have a field list 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 , we could consider rest_lint 
Intel Technology Poland
More information about the OpenStack-dev