Re: [openstack-dev] [E] [TripleO] CI Driven Documentation: Design Discussion

[Harry Rybacki]

On Tue, Jul 19, 2016 at 1:44 PM, Gordon, Kent
 wrote:
> How do I access  item [1]?
>
> [1] - http://rdo-ci-cd.etherpad.corp.redhat.com/weekly-scrum
> rdo-ci-cd.etherpad.corp.redhat.com  does not have a valid DNS entry.
>
Good catch. In short you can't. Our team is in the transition to
upstream focus -- will need to move our minutes to a new etherpad.
Relevant snippet below:

Demo: Harry Rybacki, creating tripleo-doc from CI
  Trown's PoC Review (redhat-openstack/tripleo-quickstart):
https://review.gerrithub.io/#/c/261218/
  Tracking card:
https://trello.com/c/whHpxvkO/269-investigate-ci-automated-documentation
  Prototyping role: https://github.com/HarryRybacki/tripleo-documentor

>
> Kent S. Gordon
> Verizon Wireless
>
> -Original Message-
> From: Harry Rybacki [mailto:hryba...@redhat.com]
> Sent: Tuesday, July 19, 2016 10:34 AM
> To: openstack-dev@lists.openstack.org
> Subject: [E] [openstack-dev] [TripleO] CI Driven Documentation: Design 
> Discussion
>
> All,
>
> During today's rdo-ci scrum[1], I briefed the team on PoC work that will 
> bring trown's old PoC[2] review inline with the current state of affairs of 
> TripleO-Quickstart (OOOQS) and related ansible roles used heavily in upstream 
> CI[3].
>
> To summarize, our goal is to leverage the power Sphinx[4] and templated bash 
> scripts[5] generated during jobs to decrease the overhead of maintaining 
> TripleO docs. Additionally, we aim to provide more build specific e.g., this 
> is how you would do a minimal deployment on [centos|rhelx|...], documentation 
> with as much automation as possible.
>
> In trown's initial PoC[2] conditionals are used to inside of the templates to 
> allow for selective addition of RST blocks and removal of non-useful chunks 
> of code (CI specific) for documentation[6]. The resulting docs are quite 
> aesthetically pleasing[7]. The multitude of roles which are now consumed for 
> any given build and used by OOOQS complicates things a bit.
>
> Regardless of how we move forward, roles, such as tripleo-undercloud-post[8], 
> will have to update their relevant bash templates[9].
>
> Two ideas were discussed:
>
> 1. Minimally modify the templates to have inline comments which would equate 
> to "steps" which can then be followed to reproduce a build.
>   - This would require the least work bringing roles up to speed but would in 
> turn lose the ability to use much of RST's power.
>   - This would make automated documentation incredibly easy -- just pull 
> relevant bash scripts off of the LastSuccessfullBuild from the artifacts 
> server for a given job every XX hours and
>
> 2. Modify the templates to conditionally add snippets as noted in the 
> original PoC[6].
>   - This would provide the ability to have highly customizable documentation 
> and all of the givens from using RST
>   - This would require executing roles twice (once for the build and once for 
> producing the documentation version of the scripts used during the build).
> - Other problem areas could result from this. For example, vars set 
> dynamically during a roles execution during the initial build might not be 
> available (or different) during the second execution.
>
> While I think that we should strive to have the flexibility RST provides us, 
> the MVP (option 1) already gives us (and our users) a huge leg up already 
> with continually up-to-date documentation that has been tested (and built by) 
> our CI.
>
> Any thoughts on the above would be greatly appreciated  -- perhaps there is a 
> clean way to generate two sets of templated bash in tandem and we can just 
> pull the documentation version off of the artifacts server?
>
> [1] - http://rdo-ci-cd.etherpad.corp.redhat.com/weekly-scrum
> [2] - https://review.gerrithub.io/#/c/261218/
> [3] - https://github.com/HarryRybacki/tripleo-documentor
> [4] - http://www.sphinx-doc.org/en/stable/
> [5] - 
> https://github.com/openstack/tripleo-quickstart/tree/master/roles/tripleo/undercloud/templates
> [6] - 
> https://review.gerrithub.io/#/c/261218/1/playbooks/roles/images/undercloud/templates/undercloud-run
> [7] - https://trown.fedorapeople.org/rdodocgen/
> [8] - https://github.com/redhat-openstack/ansible-role-tripleo-undercloud-post
> [9] - 
> https://github.com/redhat-openstack/ansible-role-tripleo-undercloud-post/blob/master/templates/undercloud-install-post.sh.j2
>
> Thanks, all!
>
>
> /R
>
> Harry Rybacki
> Software Engineer, Red Hat
>
> __
> 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
> 

Re: [openstack-dev] [E] [TripleO] CI Driven Documentation: Design Discussion

[Gordon, Kent]

How do I access  item [1]?

[1] - http://rdo-ci-cd.etherpad.corp.redhat.com/weekly-scrum
rdo-ci-cd.etherpad.corp.redhat.com  does not have a valid DNS entry.


Kent S. Gordon
Verizon Wireless

-Original Message-
From: Harry Rybacki [mailto:hryba...@redhat.com] 
Sent: Tuesday, July 19, 2016 10:34 AM
To: openstack-dev@lists.openstack.org
Subject: [E] [openstack-dev] [TripleO] CI Driven Documentation: Design 
Discussion

All,

During today's rdo-ci scrum[1], I briefed the team on PoC work that will bring 
trown's old PoC[2] review inline with the current state of affairs of 
TripleO-Quickstart (OOOQS) and related ansible roles used heavily in upstream 
CI[3].

To summarize, our goal is to leverage the power Sphinx[4] and templated bash 
scripts[5] generated during jobs to decrease the overhead of maintaining 
TripleO docs. Additionally, we aim to provide more build specific e.g., this is 
how you would do a minimal deployment on [centos|rhelx|...], documentation with 
as much automation as possible.

In trown's initial PoC[2] conditionals are used to inside of the templates to 
allow for selective addition of RST blocks and removal of non-useful chunks of 
code (CI specific) for documentation[6]. The resulting docs are quite 
aesthetically pleasing[7]. The multitude of roles which are now consumed for 
any given build and used by OOOQS complicates things a bit.

Regardless of how we move forward, roles, such as tripleo-undercloud-post[8], 
will have to update their relevant bash templates[9].

Two ideas were discussed:

1. Minimally modify the templates to have inline comments which would equate to 
"steps" which can then be followed to reproduce a build.
  - This would require the least work bringing roles up to speed but would in 
turn lose the ability to use much of RST's power.
  - This would make automated documentation incredibly easy -- just pull 
relevant bash scripts off of the LastSuccessfullBuild from the artifacts server 
for a given job every XX hours and

2. Modify the templates to conditionally add snippets as noted in the original 
PoC[6].
  - This would provide the ability to have highly customizable documentation 
and all of the givens from using RST
  - This would require executing roles twice (once for the build and once for 
producing the documentation version of the scripts used during the build).
- Other problem areas could result from this. For example, vars set 
dynamically during a roles execution during the initial build might not be 
available (or different) during the second execution.

While I think that we should strive to have the flexibility RST provides us, 
the MVP (option 1) already gives us (and our users) a huge leg up already with 
continually up-to-date documentation that has been tested (and built by) our CI.

Any thoughts on the above would be greatly appreciated  -- perhaps there is a 
clean way to generate two sets of templated bash in tandem and we can just pull 
the documentation version off of the artifacts server?

[1] - http://rdo-ci-cd.etherpad.corp.redhat.com/weekly-scrum
[2] - https://review.gerrithub.io/#/c/261218/
[3] - https://github.com/HarryRybacki/tripleo-documentor
[4] - http://www.sphinx-doc.org/en/stable/
[5] - 
https://github.com/openstack/tripleo-quickstart/tree/master/roles/tripleo/undercloud/templates
[6] - 
https://review.gerrithub.io/#/c/261218/1/playbooks/roles/images/undercloud/templates/undercloud-run
[7] - https://trown.fedorapeople.org/rdodocgen/
[8] - https://github.com/redhat-openstack/ansible-role-tripleo-undercloud-post
[9] - 
https://github.com/redhat-openstack/ansible-role-tripleo-undercloud-post/blob/master/templates/undercloud-install-post.sh.j2

Thanks, all!


/R

Harry Rybacki
Software Engineer, Red Hat

__
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