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