Open Stack

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:hrybacki at redhat.com] 
Sent: Tuesday, July 19, 2016 10:34 AM
To: openstack-dev at 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-request at lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev