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