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


The Bash script can then be converted to RST, e.g.:


Source Code:


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:

Here's the getting started guide we wrote for Heat using this:

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.


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


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe

OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe

Reply via email to