Re: [openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
> Excerpts from Dan Prince's message of 2015-04-13 14:07:28 -0700: > > On Tue, 2015-04-07 at 21:06 +, 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
Re: [openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
Excerpts from Dan Prince's message of 2015-04-13 14:07:28 -0700: > On Tue, 2015-04-07 at 21:06 +, 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
Re: [openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
On Tue, 2015-04-07 at 21:06 +, 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
Re: [openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
Excerpts from Clint Byrum's message of 2015-04-08 23:11:29 +: > > I discussed a format for something similar here: > > https://review.openstack.org/#/c/162267/ > > Perhaps we could merge the effort. > > The design and implementation in that might take some time, but if we > can document the variables at the same time we prepare the inputs for > isolation, that seems like a winning path forward. > The solution presented there would be awesome for not having to document the variables manually at all - we can do some sphinx plugin magic to autogen the doc sections and even get some annoying to write out features like static links for each var (Im sure you knew this, just spelling it out). I agree that itd be better to not put a lot of effort into switching all the README's over right now and instead work on the argument isolation. My hope is that in the meanwhile new elements we create and possibly README's we end up editing get moved over to this new format. Then, we can try and autogen something that is pretty similar when the time comes. Now, lets get that arg isolation donw already. ;) Cheers, Greg __ 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
Re: [openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
Excerpts from Gregory Haynes's message of 2015-04-07 14:06:52 -0700: > 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 discussed a format for something similar here: https://review.openstack.org/#/c/162267/ Perhaps we could merge the effort. The design and implementation in that might take some time, but if we can document the variables at the same time we prepare the inputs for isolation, that seems like a winning path forward. __ 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
Re: [openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
> 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? > > 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 Looks very promising. Are you planning to add some kind of lint[1] to RST and force formatting or based on common sense for all developers involved? One minor thing: would be nice to have permalinks to Variables. In general, it's more readable and understandable compared to previous version. +1 from me :) [1] https://pypi.python.org/pypi/restructuredtext_lint/0.4.0 -- 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
Re: [openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
+2 from me. I'm still in favor of killing off most/all input env vars and coming up with a less error-prone way to handle configuration, but in the meantime this is a big step toward sanity for users. On 04/07/2015 04:06 PM, 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? > > 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
[openstack-dev] [TripleO] Consistent variable documentation for diskimage-builder elements
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? 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
