[openstack-dev] [docs] Automating documentation the tripleo way?

Discussion:

Petr Kovar

2018-05-16 15:39:14 UTC

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

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-***@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-b

Ben Nemec

2018-05-16 17:11:24 UTC

Permalink

Post by Petr Kovar
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
https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2
https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/
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

Doug Hellmann

2018-05-16 18:40:47 UTC

Permalink

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

Wesley Hayutin

2018-05-16 19:26:46 UTC

Permalink

Post by Petr Kovar

Post by Doug Hellmann

last

Post by Doug Hellmann

Post by Petr Kovar
Summit (https://etherpad.openstack.org/p/SYD-install-guide-testing).
It was brought to my attention that the tripleo team has been

working on

Post by Doug Hellmann

Post by Petr Kovar
automating some of the tripleo deployment procedures, using a Bash

script

Post by Doug Hellmann

Post by Petr Kovar
with included comment lines to supply some RST-formatted narrative,

for
https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2
https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/
https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs

Post by Doug Hellmann

Post by Petr Kovar
I really liked this approach and while I don't want to sound like

selling

Post by Doug Hellmann

Post by Petr Kovar
other people's work, I'm wondering if there is still an interest

among

Post by Doug Hellmann
the

Post by Petr Kovar
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

Post by Doug Hellmann
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.

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

Post by Petr Kovar
Doug

What do you think?
[1] https://docs.openstack.org/queens/deploy/

__________________________________________________________________________

Post by Doug Hellmann
OpenStack Development Mailing List (not for usage questions)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Harry Rybacki

2018-05-16 19:46:55 UTC

Permalink

Post by Doug Hellmann

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.
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.
What do you think?

Interesting idea -- discussing this a bit at Summit (for those who
will be in attendance) seems like a good place to start.

[1] https://docs.openstack.org/queens/deploy/

Post by Doug Hellmann
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Alex Schultz

2018-05-16 19:34:26 UTC

Permalink

Post by Petr Kovar

https://github.com/openstack/tripleo-quickstart-extras/blob/master/roles/overcloud-prep-images/templates/overcloud-prep-images.sh.j2
https://thirdparty.logs.rdoproject.org/jenkins-tripleo-quickstart-queens-rdo_trunk-baremetal-dell_fc430_envB-single_nic_vlans-27/docs/build/
https://github.com/openstack/tripleo-quickstart-extras/tree/master/roles/collect-logs

Post by Petr Kovar
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

Post by Petr Kovar
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.

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.

We publish on docs.o.o. It's the same docs, just different theme.

https://docs.openstack.org/tripleo-docs/latest/install/index.html
https://docs.openstack.org/tripleo-docs/latest/contributor/index.html

I guess we could just change the tripleo.org to redirect to the
docs.o.o stuff. I'm not sure the history behind this. I would say
that you can't really find them from the main docs.o.o page unless you
search so maybe that's part of it? I'm assuming this is likely because
we don't version our docs in the past so they don't show up. Is there
a better way to ensure visibility of docs?

Thanks,
-Alex

Post by Petr Kovar
That said, publishing a new deployment guide based on this technique
makes sense in general. What about Ben's comments elsewhere in the
thread?
Doug

What do you think?
[1] https://docs.openstack.org/queens/deploy/

Post by Petr Kovar
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-***@lists.openstack.org?subject:unsubscribe
http://list