Open Stack

On 16/05/18 13:11, Ben Nemec wrote:
> 
> 
> On 05/16/2018 10:39 AM, Petr Kovar wrote:
>> Hi all,
>>
>> In the past few years, we've seen several efforts aimed at automating
>> procedural documentation, mostly centered around the OpenStack
>> installation guide. This idea to automatically produce and verify
>> installation steps or similar procedures was mentioned again at the last
>> Summit (https://etherpad.openstack.org/p/SYD-install-guide-testing).
>>
>> It was brought to my attention that the tripleo team has been working on
>> automating some of the tripleo deployment procedures, using a Bash script
>> with included comment lines to supply some RST-formatted narrative, for
>> example:
>>
>> https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2 
>>
>>
>> The Bash script can then be converted to RST, e.g.:
>>
>> https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/ 
>>
>>
>> Source Code:
>>
>> https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs 
>>
>>
>> I really liked this approach and while I don't want to sound like selling
>> other people's work, I'm wondering if there is still an interest among 
>> the
>> broader OpenStack community in automating documentation like this?
> 
> I think it's worth noting that TripleO doesn't even use the generated 
> docs.  The main reason is that we tried this back in the 
> tripleo-incubator days and it was not the silver bullet for good docs 
> that it appears to be on the surface.  As the deployment scripts grow 
> features and more complicated logic it becomes increasingly difficult to 
> write inline documentation that is readable.  In the end, the 
> tripleo-incubator docs had a number of large bash snippets that referred 
> to internal variables and such.  It wasn't actually good documentation.

FWIW in the early days of Heat I had an implementation that did this in 
the opposite direction: the script was extracted from the (rst) 
documentation, instead of extracting the documentation from the script. 
This is the way you need to do it to work around the kinds of concerns 
you mention. (Bash will try to execute literally anything that isn't a 
comment; rst makes it much easier to overload the meanings of different 
constructs.)

Basically how it worked was that everything that was indented by 4 
spaces in the rst file was extracted into the script - this could be a 
code block (which of course appeared as a code block in the 
documentation) or a comment block (which didn't). This enabled you to 
hide stuff that is boring but necessary to make the script work from the 
documentation. You could also do actual comments or code blocks that 
didn't appear in the script (e.g. for giving alternate implementations) 
by indenting only 2 spaces.

The actual extraction was done by this fun sed script:
http://git.openstack.org/cgit/openstack/heat/plain/tools/rst2script.sed?id=95e5ed067096ff52bbcd6c49146b74e1d59d2d3f

Here's the getting started guide we wrote for Heat using this:
http://git.openstack.org/cgit/openstack/heat/plain/docs/GettingStarted.rst?id=c0c1768e4a2b441ef286fb49c60419be3fe80786

In the end we didn't keep it around. I think mostly because we weren't 
able to actually run the script in the gate at the time (2012), and 
because after Heat support was added to devstack the getting started 
guide essentially reduced to 'use devstack' (did I mention it was 
2012?). So we didn't gain any long term experience in whether this is a 
good idea or not, although we did maintain it somewhat successfully for 
a year. But if you're going to try to do something similar then I'd 
recommend this method as a starting point.

cheers,
Zane.

> When we moved to instack-undercloud to drive TripleO deployments we also 
> moved to a more traditional hand-written docs repo.  Both options have 
> their benefits and drawbacks, but neither absolves the development team 
> of their responsibility to curate the docs.  IME the inline method 
> actually makes it harder to do this because it tightly couples your code 
> and docs in a very inflexible way.
> 
> /2 cents
> 
> -Ben
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev