[openstack-dev] [docs] Automating documentation the tripleo way?
openstack at nemebean.com
Wed May 16 17:11:24 UTC 2018
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.
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.
More information about the OpenStack-dev