Open Stack

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.

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