Open Stack

Greetings All,

Detailed post TripleO-Quickstart build doc generation is coming along
smoothly. After much discussion between myself, adarazs, weshay, and
larsks -- I believe to have found a solution that impacts
TripleO-Quickstart and external roles minimally. Combining work from
trown[1] and an old awk script from way-back-when, all we need is to:

  1. Ensure as much work is done within templated bash scripts as
possible (this was/is already a goal of oooq)
  2. Track which templates are used for build paths e.g. for a
"minimal" deployment the following shell scripts are created and
called:
      - undercloud-install.sh
      - undercloud-post-instal.sh
      - overcloud-deploy.sh
      - overcloud-deploy-post.sh
      - overcloud-validate.sh
  3. Update existing/audit new templates to follow some style
guidelines[3] (vanilla example as well as an actual script output
linked in this paste).

After a build has finished, either by way of CI or locally, the
tripleo-collect-logs[4] role can be used to collect logs from the
undercloud, convert the shell scripts into rST files, use Sphinx[5] to
build a documentation, and (optionally) publish the results to an
artifacts server.

There is a PoC job[6] up that is successfully building and publishing
docs created to combine and monitor work done in relevant
tripleo-quickstart[7] and ansible-role-tripleo-collect-logs[8]
patches. To get a better idea of what the end product from Sphinx
looks like, please look here[9]. Note that the job is using a playbook
which is calling external roles for most of the deployment (which
doesn't contain all the possible templated bash script conversions).
For a more complete version, download the output from a local run I
completed yesterday[10] -- just untar it and open the index.html file
located at its root level.

Up to this point, my goal has been to get as much coverage of what our
CI does in a minimal job[10] building documentation. With this shaping
up quickly, I would like to open discussion around what I believe will
be the most complicated part of expanding documentation coverage -
work being done via ansible instead of within templated bash scripts.
For example, the undercloud role in TripleO-Quickstart adjusts an
Ironic config and restarts the service[11] outside of the templated
bash scripts. I can see a few solutions:

  1. Convert work done in ansible to templated bash scripts
      - Requires a fair amount of initial leg work
      - Sections of the workflow very well /should/ be ansible for
various reasons
  2. Write static documentation for things not templated and insert it
inti the correct section of docs
      - Propensity to very easily become out-of-date
  3. Write templated bash that mimics what ansible is doing and let
the automation consume these unused 'scripts'
      - Same issue as option 2 -- both allow for easy divergence
between what is done in automation and what we are presenting folks
with inside of the docs

Would folks chime in on the above? Is there a simple solution that I overlooked?

[1] - https://review.gerrithub.io/#/c/261218/
[2] - https://github.com/openstack/tripleo-incubator/blob/master/scripts/extract-docs.awk
[3] - https://paste.fedoraproject.org/408991/
[4] - https://github.com/redhat-openstack/ansible-role-tripleo-collect-logs
[5] - http://www.sphinx-doc.org/en/stable/
[6] - https://ci.centos.org/job/poc-hrybacki-tripleo-quickstart-roles-gate-mitaka-doc-generator/
full-minimal/
[7] - https://review.openstack.org/#/c/347592/
[8] - https://review.gerrithub.io/#/c/286349/
[9] - https://ci.centos.org/artifacts/rdo/jenkins-poc-hrybacki-tripleo-quickstart-roles-gate-mitaka-doc-generator-44/docs/build/
[10] - https://drive.google.com/a/redhat.com/file/d/0B9Alqh5AS1vpS1djWm9zYmZhNHM/view?usp=sharing
[11] - https://ci.centos.org/view/rdo/view/tripleo-gate/job/tripleo-quickstart-gate-mitaka-delorean-
[12] - https://github.com/openstack/tripleo-quickstart/blob/master/roles/tripleo/undercloud/tasks/main.yml#L9-L21


/R

Harry Rybacki