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

[Zane Bitter]

On 16/05/18 13:11, Ben Nemec wrote:



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.


FWIW in the early days of Heat I had an implementation that did this in 
the opposite direction: the script was extracted from the (rst) 
documentation, instead of extracting the documentation from the script. 
This is the way you need to do it to work around the kinds of concerns 
you mention. (Bash will try to execute literally anything that isn't a 
comment; rst makes it much easier to overload the meanings of different 
constructs.)


Basically how it worked was that everything that was indented by 4 
spaces in the rst file was extracted into the script - this could be a 
code block (which of course appeared as a code block in the 
documentation) or a comment block (which didn't). This enabled you to 
hide stuff that is boring but necessary to make the script work from the 
documentation. You could also do actual comments or code blocks that 
didn't appear in the script (e.g. for giving alternate implementations) 
by indenting only 2 spaces.


The actual extraction was done by this fun sed script:
http://git.openstack.org/cgit/openstack/heat/plain/tools/rst2script.sed?id=95e5ed067096ff52bbcd6c49146b74e1d59d2d3f

Here's the getting started guide we wrote for Heat using this:
http://git.openstack.org/cgit/openstack/heat/plain/docs/GettingStarted.rst?id=c0c1768e4a2b441ef286fb49c60419be3fe80786

In the end we didn't keep it around. I think mostly because we weren't 
able to actually run the script in the gate at the time (2012), and 
because after Heat support was added to devstack the getting started 
guide essentially reduced to 'use devstack' (did I mention it was 
2012?). So we didn't gain any long term experience in whether this is a 
good idea or not, although we did maintain it somewhat successfully for 
a year. But if you're going to try to do something similar then I'd 
recommend this method as a starting point.


cheers,
Zane.

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



__
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

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

[Wesley Hayutin]

On Thu, May 17, 2018 at 10:22 AM Petr Kovar  wrote:

> On Wed, 16 May 2018 13:26:46 -0600
> Wesley Hayutin  wrote:
>
> > On Wed, May 16, 2018 at 3:05 PM Doug Hellmann 
> 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  >
> > > 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.
>
>
> Yes, I wasn't very clear on the goals as I didn't want to make too many
> assumptions before learning about technical details from other people.
> Ben's comments made me realize this approach would probably be best suited
> for generating documents such as quick start guides or tutorials that are
> procedural, yet they don't aim at describing multiple use cases.
>
>
> > > >
> > > > 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.
>
>
> Would it make sense to consider a bot automatically creating patches
> 

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

[Petr Kovar]

On Wed, 16 May 2018 13:26:46 -0600
Wesley Hayutin  wrote:

> On Wed, May 16, 2018 at 3:05 PM Doug Hellmann  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 
> > 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.


Yes, I wasn't very clear on the goals as I didn't want to make too many
assumptions before learning about technical details from other people.
Ben's comments made me realize this approach would probably be best suited
for generating documents such as quick start guides or tutorials that are
procedural, yet they don't aim at describing multiple use cases.


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


Would it make sense to consider a bot automatically creating patches
with content updates that would be then curated and reviewed by the docs
contributors?


>  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 

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

[Roger Luethi]

On 16.05.18 20:40, Doug Hellmann wrote:

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.


training-labs uses its own installer because the project goal is to do 
the full deployment (that is, including the creation of appropriate VMs) 
in an automated fashion on all supported platforms (Linux, macOS, 
Windows). The scripts that are injected into the VMs follow the 
install-guide as closely as possible. We were pretty close to automating 
the translation from install-guide docs to shell scripts, but some 
issues remained (e.g., some scripts need guards waiting for services to 
come up in order to avoid race conditions; this is not documented in the 
install-guide).


Roger

__
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

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

[Harry Rybacki]

On Wed, May 16, 2018 at 2:51 PM, Wesley Hayutin  wrote:
>
>
> On Wed, May 16, 2018 at 2:41 PM Doug Hellmann  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.
>
> 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/
>
>
>>
>>
>> __
>> 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
>
>
> __
> 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
>

__
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

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

[Alex Schultz]

On Wed, May 16, 2018 at 1:04 PM, Doug Hellmann  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  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.
>

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

> 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/
>>
>> >
>> > __
>> > 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
>> >
>
> __
> 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

__
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

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

[Wesley Hayutin]

On Wed, May 16, 2018 at 3:05 PM Doug Hellmann  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 
> 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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>

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

[Doug Hellmann]

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

Doug

> 
> What do you think?
> 
> [1] https://docs.openstack.org/queens/deploy/
> 
> >
> > __
> > 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
> >

__
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

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

[Wesley Hayutin]

On Wed, May 16, 2018 at 2:41 PM Doug Hellmann  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.

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?

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



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

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

[Doug Hellmann]

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

__
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

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

[Ben Nemec]

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

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

[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
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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev