Open Stack

> 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