Open Stack

On Wed, May 16, 2018 at 3:05 PM Doug Hellmann <doug at doughellmann.com> wrote:

> Excerpts from Wesley Hayutin's message of 2018-05-16 12:51:25 -0600:
> > On Wed, May 16, 2018 at 2:41 PM Doug Hellmann <doug at doughellmann.com>
> wrote:
> >
> > > Excerpts from Petr Kovar's message of 2018-05-16 17:39:14 +0200:
> > > > 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?
> > > >
> > > > Thanks,
> > > > pk
> > > >
> > >
> > > Weren't the folks doing the training-labs or training-guides taking a
> > > similar approach? IIRC, they ended up implementing what amounted to
> > > their own installer for OpenStack, and then ended up with all of the
> > > associated upgrade and testing burden.
> > >
> > > I like the idea of trying to use some automation from this, but I
> wonder
> > > if we'd be better off extracting data from other tools, rather than
> > > building a new one.
> > >
> > > Doug
> > >
> >
> > So there really isn't anything new to create, the work is done and
> executed
> > on every tripleo change that runs in rdo-cloud.
>
> It wasn't clear what Petr was hoping to get. Deploying with TripleO is
> only one way to deploy, so we wouldn't be able to replace the current
> installation guides with the results of this work. It sounds like that's
> not the goal, though.
>
> >
> > Instead of dismissing the idea upfront I'm more inclined to set an
> > achievable small step to see how well it works.  My thought would be to
> > focus on the upcoming all-in-one installer and the automated doc
> generated
> > with that workflow.  I'd like to target publishing the all-in-one tripleo
> > installer doc to [1] for Stein and of course a section of tripleo.org.
>
> As an official project, why is TripleO still publishing docs to its own
> site? That's not something we generally encourage.
>
> That said, publishing a new deployment guide based on this technique
> makes sense in general. What about Ben's comments elsewhere in the
> thread?
>

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.

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.

So again, my thought is to create a small achievable goal and see where the
collaboration takes us.

Thanks


>
> Doug
>
> >
> > What do you think?
> >
> > [1] https://docs.openstack.org/queens/deploy/
> >
> > >
> > >
> __________________________________________________________________________
> > > OpenStack Development Mailing List (not for usage questions)
> > > Unsubscribe:
> OpenStack-dev-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180516/20c508b1/attachment.html>