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