<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Wed, May 16, 2018 at 3:05 PM Doug Hellmann <<a href="mailto:doug@doughellmann.com">doug@doughellmann.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Excerpts from Wesley Hayutin's message of 2018-05-16 12:51:25 -0600:<br>
> On Wed, May 16, 2018 at 2:41 PM Doug Hellmann <<a href="mailto:doug@doughellmann.com" target="_blank">doug@doughellmann.com</a>> wrote:<br>
> <br>
> > Excerpts from Petr Kovar's message of 2018-05-16 17:39:14 +0200:<br>
> > > Hi all,<br>
> > ><br>
> > > In the past few years, we've seen several efforts aimed at automating<br>
> > > procedural documentation, mostly centered around the OpenStack<br>
> > > installation guide. This idea to automatically produce and verify<br>
> > > installation steps or similar procedures was mentioned again at the last<br>
> > > Summit (<a href="https://etherpad.openstack.org/p/SYD-install-guide-testing" rel="noreferrer" target="_blank">https://etherpad.openstack.org/p/SYD-install-guide-testing</a>).<br>
> > ><br>
> > > It was brought to my attention that the tripleo team has been working on<br>
> > > automating some of the tripleo deployment procedures, using a Bash script<br>
> > > with included comment lines to supply some RST-formatted narrative, for<br>
> > > example:<br>
> > ><br>
> > ><br>
> > <a href="https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2" rel="noreferrer" target="_blank">https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2</a><br>
> > ><br>
> > > The Bash script can then be converted to RST, e.g.:<br>
> > ><br>
> > ><br>
> > <a href="https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/" rel="noreferrer" target="_blank">https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/</a><br>
> > ><br>
> > > Source Code:<br>
> > ><br>
> > ><br>
> > <a href="https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs" rel="noreferrer" target="_blank">https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs</a><br>
> > ><br>
> > > I really liked this approach and while I don't want to sound like selling<br>
> > > other people's work, I'm wondering if there is still an interest among<br>
> > the<br>
> > > broader OpenStack community in automating documentation like this?<br>
> > ><br>
> > > Thanks,<br>
> > > pk<br>
> > ><br>
> ><br>
> > Weren't the folks doing the training-labs or training-guides taking a<br>
> > similar approach? IIRC, they ended up implementing what amounted to<br>
> > their own installer for OpenStack, and then ended up with all of the<br>
> > associated upgrade and testing burden.<br>
> ><br>
> > I like the idea of trying to use some automation from this, but I wonder<br>
> > if we'd be better off extracting data from other tools, rather than<br>
> > building a new one.<br>
> ><br>
> > Doug<br>
> ><br>
> <br>
> So there really isn't anything new to create, the work is done and executed<br>
> on every tripleo change that runs in rdo-cloud.<br>
<br>
It wasn't clear what Petr was hoping to get. Deploying with TripleO is<br>
only one way to deploy, so we wouldn't be able to replace the current<br>
installation guides with the results of this work. It sounds like that's<br>
not the goal, though.<br>
<br>
> <br>
> Instead of dismissing the idea upfront I'm more inclined to set an<br>
> achievable small step to see how well it works.  My thought would be to<br>
> focus on the upcoming all-in-one installer and the automated doc generated<br>
> with that workflow.  I'd like to target publishing the all-in-one tripleo<br>
> installer doc to [1] for Stein and of course a section of <a href="http://tripleo.org" rel="noreferrer" target="_blank">tripleo.org</a>.<br>
<br>
As an official project, why is TripleO still publishing docs to its own<br>
site? That's not something we generally encourage.<br>
<br>
That said, publishing a new deployment guide based on this technique<br>
makes sense in general. What about Ben's comments elsewhere in the<br>
thread?<br></blockquote><div><br></div><div>I think Ben is referring to an older implementation and a slightly different design but still has some points that we would want to be mindful of.   I think this is a worthy effort to take another pass at this regarless to be honest as we've found a good combination of interested folks and sometimes the right people make all the difference. </div><div><br></div><div>My personal opinion is that I'm not expecting the automated doc generation to be upload ready to a doc server after each run.  I do expect it to do 95% of the work, and to help keep the doc up to date with what is executed in the latest releases of TripleO.  Also noting the doc used is a mixture of static and generated documentation which I think worked out quite well in order to not soley rely on what is executed in ci.</div><div><br></div><div>So again, my thought is to create a small achievable goal and see where the collaboration takes us.</div><div><br></div><div>Thanks</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Doug<br>
<br>
> <br>
> What do you think?<br>
> <br>
> [1] <a href="https://docs.openstack.org/queens/deploy/" rel="noreferrer" target="_blank">https://docs.openstack.org/queens/deploy/</a><br>
> <br>
> ><br>
> > __________________________________________________________________________<br>
> > OpenStack Development Mailing List (not for usage questions)<br>
> > Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> > <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
> ><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div></div>