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-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
