Open Stack

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