Integrate tripleo-documentor into tripleo-collect-logs

- Disable create-docs tasks by default
- Add artcl_create_docs_payload to direct create-docs execution

Porting functionality from tripleo-documentor[1] into the tripleo-
collect-logs role.

[1] - https://github.com/HarryRybacki/tripleo-documentor

Change-Id: Ic84e941318af6fc4ab423886f17e5347936f9cd2

README.md

@@ -7,9 +7,14 @@ Requirements
 ------------
 
 This role gathers logs and debug information from a target system and
-gathers the log in a designated directory on the localhost.
+collates them in a designated directory, `artcl_collect_dir`, on the localhost.
 
-The role also takes care of uploading these logs to an rsync server.
+Additionally, the role will convert templated bash scripts, created and used by
+TripleO-Quickstart during deployment, into rST files. These rST files are
+combined with static rST files and fed into Sphinx to create user friendly
+post-build-documentation specific to an original deployment.
+
+Finally, the role optionally handles uploading these logs to a rsync server.
 
 Role Variables
 --------------
@@ -26,18 +31,46 @@ artcl_collect_list:
     - /var/log
 ```
 
-* `artcl_collect_dir` -- a local directory where the logs should be
+* `artcl_collect_dir` -- A local directory where the logs should be
   gathered, without a trailing slash.
-* `artcl_gzip_only`: false/true  -- When true, gathered files are gzipped one by
+* `artcl_gzip_only`: false/true  -- When true, gathered files are gzipped one
-  one in `artcl_collect_dir`, when false, a tar.gz file will contain all the
+  by one in `artcl_collect_dir`, when false, a tar.gz file will contain all the
   logs.
+* `artcl_gen_docs`: true/false -- If true, the role will use build artifacts
+  and Sphinx and produce user friendly documentation.
+* `artcl_docs_source_dir` -- a local directory that serves as the Sphinx source
+  directory.
+* `artcl_docs_build_dir` -- A local directory that serves as the Sphinx build
+  output directory.
+* `artcl_create_docs_payload` -- Dictionary of lists that direct what and how
+  to construct documentation.
+    * `included_deployment_scripts` -- List of templated bash scripts to be
+      converted to rST files.
+    * `included_deployment_scripts` -- List of static rST files that will be
+      included in the output documentation.
+    * `table_of_contents` -- List that defines the order in which rST files
+      will be laid out in the output documentation.
+
+```yaml
+artcl_create_docs_payload:
+  included_deployment_scripts:
+    - undercloud-install
+    - undercloud-post-install
+  included_static_docs:
+    - env-setup-virt
+  table_of_contents:
+    - env-setup-virt
+    - undercloud-install
+    - undercloud-post-install
+```
+
 * `artcl_publish`: true/false -- If true, the role will attempt to rsync logs
   to the target specified by `artcl_rsync_url`. Uses `BUILD_URL`, `BUILD_TAG`
   vars from the environment (set during a Jenkins job run) and requires the
   next to variables to be set.
 * `artcl_rsync_url` -- rsync target for uploading the logs. The localhost
   needs to have passwordless authentication to the target or the
-  `PROVISIONER_KEY` var specificed in the environment.
+  `PROVISIONER_KEY` Var specificed in the environment.
 * `artcl_artifact_url` -- a HTTP URL at which the uploaded logs will be
   accessible after upload.
 
@@ -52,6 +85,23 @@ Example Playbook
     - tripleo-collect-logs
 ```
 
+Templated Bash to rST Conversion Notes
+--------------------------------------
+
+Templated bash scripts used during deployment are converted to rST files
+during the `create-docs` portion of the role's call. Shell scripts are
+fed into an awk script and output as restructured text. The awk script
+has several simple rules:
+
+1. Only lines between `### ---start_docs` and `### ---stop_docs` will be
+  parsed.
+2. Lines containing `# nodoc` will be excluded.
+3. Lines containing `## ::` indicate subsequent lines should be formatted
+  as code blocks
+4. Other lines beginning with `## <anything else>` will have the prepended
+   `## ` removed. This is how and where general rST formatting is added.
+5. All other lines, including shell comments, will be indented by four spaces.
+
 License
 -------
 

defaults/main.yml

@@ -30,3 +30,8 @@ artcl_collect_dir: "{{ lookup('env', 'PWD') }}/collected_files"
 artcl_gzip_only: true
 artcl_collect: true
 artcl_publish: false
+
+## Doc generation specific vars
+artcl_gen_docs: false
+artcl_docs_source_dir: "{{ local_working_dir }}/usr/local/share/ansible/roles/tripleo-collect-logs/docs/source"
+artcl_docs_build_dir: "{{ artcl_collect_dir }}/docs/build"

doc-requirements.txt

@@ -0,0 +1,5 @@
+# Doc requirements
+sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+oslosphinx>=2.2.0  # Apache-2.0
+sphinx_rtd_theme==0.1.7
+ansible

docs/source/_custom/custom.css

@@ -0,0 +1,226 @@
+@import url("css/theme.css");
+@import url("rdo_styling.css");
+
+/* CUSTOM CSS OVERRIDES GO HERE */
+/* ============================ */
+
+
+/* LAYOUT */
+.wy-nav-side {
+  overflow: visible;
+}
+
+.wy-side-nav-search {
+  margin-bottom: 0;
+}
+
+.wy-nav-content-wrap {
+  background: white;
+}
+
+.wy-nav-content {
+  max-width: 100%;
+  box-sizing: border-box;
+}
+
+.rst-content .section ol li p.first:last-child {
+    margin-bottom: 24px;
+}
+
+
+/* LOGO */
+.wy-side-nav-search a {
+  margin-bottom: 5px;
+}
+
+.wy-side-nav-search img {
+  background: none;
+  border-radius: 0;
+  height: 60px;
+  width: auto;
+  margin: 0;
+}
+
+
+/* TYPOGRAPHY */
+p {
+  margin-bottom: 16px;
+}
+
+p + ul, p + ol.simple {
+  margin-top: -12px;
+}
+
+h1, h2, h3, h4, h5, h6, p.rubric {
+  margin-top: 48px;
+}
+
+h2 {
+  border-bottom: 1px solid rgba(0, 0, 0, 0.2);
+}
+
+
+/* BREADCRUMBS */
+
+.wy-breadcrumbs {
+  font-size: 85%;
+  color: rgba(0, 0, 0, 0.45);
+}
+
+.wy-breadcrumbs a {
+  text-decoration: underline;
+  color: inherit;
+}
+
+.wy-breadcrumbs a:hover,
+.wy-breadcrumbs a:focus {
+  color: rgba(0, 0, 0, 0.75);
+  text-decoration: none;
+}
+
+
+/* FOOTER */
+
+footer {
+  font-size: 70%;
+  margin-top: 48px;
+}
+
+footer p {
+  font-size: inherit;
+}
+
+
+/* NOTES, ADMONITTIONS AND TAGS */
+.admonition {
+  font-size: 85%; /* match code size */
+  background: rgb(240, 240, 240);
+  color: rgba(0, 0, 0, 0.55);
+  border: 1px solid rgba(0, 0, 0, 0.1);
+  padding: 0.5em 1em 0.75em 1em;
+  margin-bottom: 24px;
+}
+
+.admonition p {
+  font-size: inherit;
+}
+
+.admonition p.last {
+  margin-bottom: 0;
+}
+
+.admonition p.first.admonition-title {
+  display: inline;
+  background: none;
+  font-weight: bold;
+  color: rgba(0, 0, 0, 0.75);
+}
+
+/* notes */
+.rst-content .note {
+  background: rgb(240, 240, 240);
+}
+
+.note > p.first.admonition-title {
+  display: inline-block;
+  background: rgba(0, 0, 0, 0.55);
+  color: rgba(255, 255, 255, 0.95);
+}
+
+/* optional */
+.rst-content .optional {
+  background: white;
+}
+
+/* tags */
+.rhel {background: #fee;}
+.portal {background-color: #ded;}
+.satellite {background-color: #dee;}
+.centos {background: #fef;}
+.baremetal {background: #eef;}
+.virtual {background: #efe;}
+.ceph {background: #eff;}
+
+/* admonition selector */
+#admonition_selector {
+  color: white;
+  font-size: 85%;
+  line-height: 1.4;
+  background: #2980b9;
+  border-top: 1px solid rgba(255, 255, 255, 0.4);
+}
+
+.trigger {
+  display: block;
+  font-size: 110%;
+  color: rgba(255, 255, 255, 0.75);
+  line-height: 2.5;
+  position: relative;
+  cursor: pointer;
+  padding: 0 1.618em;
+}
+
+.trigger:after {
+  content: '';
+  display: block;
+  font-family: FontAwesome;
+  font-size: 70%;
+  position: absolute;
+  right: 1.618em;
+  top: 6px;
+}
+
+.trigger:hover {
+  color: white;
+}
+
+.content {
+  display: none;
+  border-top: 1px solid rgba(255, 255, 255, 0.1);
+  background: rgba(255, 255, 255, 0.1);
+  padding: 0.5em 1.618em;
+}
+
+.displayed .trigger:after {
+  content: '';
+}
+
+#admonition_selector .title {
+  color: rgba(255, 255, 255, 0.45);
+}
+
+#admonition_selector ul {
+  margin-bottom: 0.75em;
+}
+
+#admonition_selector ul li {
+  display: block;
+}
+
+#admonition_selector label {
+  display: inline;
+  color: inherit;
+  text-decoration: underline dotted;
+}
+
+
+/* LINKS */
+a.external:after {
+  font-family: FontAwesome;
+  content: '';
+  visibility: visible;
+  display: inline-block;
+  font-size: 70%;
+  position: relative;
+  padding-left: 0.5em;
+  top: -0.5em;
+}
+
+
+/* LIST */
+.wy-plain-list-decimal > li > ul,
+.rst-content .section ol > li > ul,
+.rst-content ol.arabic > li > ul,
+article ol > li > ul {
+    margin-bottom: 24px;
+}

docs/source/_custom/rdo_styling.css

@@ -0,0 +1,208 @@
+/* general settings */
+body {
+  font-family: "Open Sans", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  font-size: 16px;
+}
+
+
+/* remove backgrounds */
+.wy-nav-content,
+.wy-body-for-nav,
+.wy-nav-side,
+#admonition_selector {
+  background: none !important;
+  color: black !important;
+}
+
+
+/* page header */
+.wy-side-nav-search,
+.wy-nav-top {
+  background: rgba(0, 0, 0, 0.05) !important;
+}
+
+.wy-nav-top {
+  line-height: 40px;
+  border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.wy-side-nav-search a,
+.wy-nav-top a,
+.wy-nav-top i {
+  color: rgb(160, 0, 0) !important;
+}
+
+.wy-nav-top i {
+  position: relative;
+  top: 0.1em;
+}
+
+.wy-side-nav-search input[type="text"] {
+  border-color: rgba(0, 0, 0, 0.25);
+}
+
+
+/* sidebar*/
+.wy-nav-side {
+  border-right: 1px solid rgba(0, 0, 0, 0.2);
+}
+
+
+/* admonition selector */
+#admonition_selector {
+  border-top: 0 none !important;
+}
+
+.trigger {
+  color: rgba(0, 0, 0, 0.7) !important;
+  border-top: 1px solid rgba(0, 0, 0, 0.2);
+  border-bottom: 1px solid rgba(0, 0, 0, 0.2);
+  background: rgba(0, 0, 0, 0.05);
+}
+
+.trigger:hover {
+  color: rgba(0, 0, 0, 0.9) !important;
+}
+
+.content {
+  border-top: 0 none !important;
+  border-bottom: 1px solid rgba(0, 0, 0, 0.2) !important;
+  background: rgba(0, 0, 0, 0.025) !important;
+}
+
+#admonition_selector .title {
+  color: rgba(0, 0, 0, 0.6) !important;
+}
+
+
+/* menu */
+.wy-menu li a,
+.wy-menu-vertical li a {
+  font-size: 100%;
+  line-height: 1.6;
+  color: rgb(80, 80, 80);
+}
+
+.wy-menu-vertical li a:hover,
+.wy-menu-vertical li a:focus,
+.wy-menu-vertical li.current a:hover,
+.wy-menu-vertical li.current a:focus {
+  color: black;
+  text-decoration: underline;
+  background: none;
+}
+
+.wy-menu-vertical li.current,
+.wy-menu-vertical li.current a {
+  border: 0 none;
+  color: rgb(80, 80, 80);
+  font-weight: inherit;
+  background: none;
+}
+
+/* level-1 menu item */
+.wy-menu-vertical li.toctree-l1.current > a,
+.wy-menu-vertical li.toctree-l1.current > a:hover,
+.wy-menu-vertical li.toctree-l1.current > a:focus {
+  background: rgb(230, 230, 230);
+}
+
+.wy-menu li.toctree-l1 > a:before {
+  font-family: FontAwesome;
+  content: "";
+  display: inline-block;
+  position: relative;
+  padding-right: 0.5em;
+}
+
+/* level-2 menu item */
+.toctree-l2 {
+  font-size: 90%;
+  color: inherit;
+}
+
+.wy-menu-vertical .toctree-l2 a {
+  padding: 0.4045em 0.5em 0.4045em 2.8em !important;
+}
+
+.wy-menu-vertical li.toctree-l2.current > a,
+.wy-menu-vertical li.toctree-l2.current > a:hover,
+.wy-menu-vertical li.toctree-l2.current > a:focus,
+.wy-menu-vertical li.toctree-l2.active > a,
+.wy-menu-vertical li.toctree-l2.active > a:hover,
+.wy-menu-vertical li.toctree-l2.active > a:focus {
+  background: rgb(242, 242, 242);
+}
+
+.wy-menu li.toctree-l2 > a:before {
+  font-family: FontAwesome;
+  content: "";
+  font-size: 30%;
+  display: inline-block;
+  position: relative;
+  bottom: 0.55em;
+  padding-right: 1.5em;
+}
+
+
+/* typography */
+h1 {
+  color: rgb(160, 0, 0);
+  font-weight: 300;
+  margin-top: 36px !important;
+}
+
+h3 {
+  font-size: 135%;
+}
+
+h2, h3, h4, h5 {
+  font-weight: 200;
+}
+
+
+a, a:visited {
+  color: #2275b4;
+  text-decoration: none;
+}
+
+a:hover, a:focus {
+  color: #1c6094;
+  text-decoration: underline;
+}
+
+.rst-content .toc-backref {
+  color: inherit;
+}
+
+strong {
+  font-weight: 600;
+}
+
+
+/* code */
+.codeblock,
+pre.literal-block,
+.rst-content .literal-block,
+.rst-content pre.literal-block,
+div[class^="highlight"] {
+  background: rgba(0, 0, 0, 0.05);
+  color: black;
+}
+
+
+/* notes */
+.admonition {
+  color: rgba(0, 0, 0, 0.5) !important;
+  font-weight: 400;
+}
+
+.rst-content .note {
+  background: none !important;
+}
+
+.note > p.first.admonition-title {
+  background: rgba(0, 0, 0, 0.5) !important;
+  color: rgba(255, 255, 255, 0.9) !important;
+}

docs/source/_templates/layout.html

@@ -0,0 +1 @@
+{% extends "!layout.html" %}

docs/source/conf.py

@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+#
+# instack-undercloud documentation build configuration file, created by
+# sphinx-quickstart on Wed Feb 25 10:56:57 2015.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+import sphinx_rtd_theme
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme_options = {}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'TripleO'
+copyright = u'2016, RDO CI Team'
+bug_tracker = u'Bugzilla'
+bug_tracker_url = u'https://bugzilla.redhat.com'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '3.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '3.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_static_path = ['_custom']
+html_style = 'custom.css'
+html_last_updated_fmt = '%b %d, %Y'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'tripleo-documentor'
+
+html_show_sourcelink = True
+html_show_sphinx = True
+html_show_copyright = True
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+rst_prolog = """
+.. |project| replace:: %s
+.. |bug_tracker| replace:: %s
+.. |bug_tracker_url| replace:: %s
+""" % (project, bug_tracker, bug_tracker_url)

docs/static/env-setup-virt.rst

@@ -0,0 +1,65 @@
+Virtual Environment
+===================
+
+|project| Quickstart can be used in a virtual environment using virtual machines instead
+of actual baremetal. However, one baremetal machine ( VIRTHOST ) is still
+needed to act as the host for the virtual machines.
+
+
+Minimum System Requirements
+---------------------------
+
+By default, this setup creates 3 virtual machines:
+
+* 1 Undercloud
+* 1 Overcloud Controller
+* 1 Overcloud Compute
+
+.. note::
+   Each virtual machine must consist of at least 4 GB of memory and 40 GB of disk
+   space.
+   The virtual machine disk files are thinly provisioned and will not take up
+   the full 40GB initially.
+
+You will need a baremetal host machine (referred to as ``$VIRTHOST``) with at least
+**16G** of RAM, preferably **32G**, and you must be able to ``ssh`` to the
+virthost machine as root without a password from the machine running ansible.
+Currently the virthost machine must be running a recent Red Hat-based Linux
+distribution (CentOS 7, RHEL 7, Fedora 22 - only CentOS 7 is currently tested),
+but we hope to add support for non-Red Hat distributions too.
+
+|project| Quickstart currently supports the following operating systems:
+
+* CentOS 7 x86_64
+
+TripleO Quickstart
+------------------
+
+TripleO Quickstart is a fast and easy way to setup and configure your virtual environment for TripleO.
+Further documentation can be found at https://github.com/openstack/tripleo-quickstart
+
+A quick way to test that your virthost machine is ready to rock is::
+
+    ssh root@$VIRTHOST uname -a
+
+Getting the script
+^^^^^^^^^^^^^^^^^^
+
+You can download the `quickstart.sh` script with `wget`::
+
+    wget https://raw.githubusercontent.com/openstack/tripleo-quickstart/master/quickstart.sh
+
+Install the dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+You need some software available on your local system before you can run
+`quickstart.sh`. You can install the necessary dependencies by running::
+
+    bash quickstart.sh --install-deps
+
+Setup your virtual environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Deploy your virtual environment by running::
+
+    bash quickstart.sh $VIRTHOST

scripts/doc_extrapolation.awk

@@ -0,0 +1,42 @@
+# AWK script used to parse shell scripts, created during TripleO deployments,
+# and convert them into rST files for digestion by Sphinx.
+#
+# General notes:
+#
+# - Only blocks between `### ---start_docs` and `### ---stop_docs` will be
+#     parsed
+# - Lines containing `# nodocs` will be excluded from rST output
+# - Lines containing `## ::` indicate subsequent lines should be formatted
+#     as code blocks
+# - Other lines beginning with `## <anything else>` will have the prepended
+#     `## ` removed. (This is how you would add general rST formatting)
+# - All other lines (including shell comments) will be indented by four spaces
+
+/^### --start_docs/ {
+    for (;;) {
+        if ((getline line) <= 0)
+            unexpected_eof()
+        if (line ~ /^### --stop_docs/)
+            break
+        if (match(line, ".* #nodocs$"))
+            continue
+        if (substr(line, 0, 5) == "## ::") {
+            line = "\n::\n"
+        } if (substr(line, 0, 3) == "## ") {
+            line = substr(line, 4)
+        } else if (line != "") {
+            line = "    "line
+        }
+        print line > "/dev/stdout"
+    }
+}
+
+function unexpected_eof() {
+    printf("%s:%d: unexpected EOF or error\n", FILENAME, FNR) > "/dev/stderr"
+    exit 1
+}
+
+END {
+    if (curfile)
+        close(curfile)
+}

setup.cfg

@@ -24,12 +24,15 @@ data_files =
     playbooks = playbooks/*
     usr/local/share/ansible/roles/tripleo-collect-logs/defaults = defaults/*
     usr/local/share/ansible/roles/tripleo-collect-logs/files = files/*
+    usr/local/share/ansible/roles/tripleo-collect-logs/docs = docs/*
     usr/local/share/ansible/roles/tripleo-collect-logs/handlers = handlers/*
     usr/local/share/ansible/roles/tripleo-collect-logs/meta = meta/*
+    usr/local/share/ansible/roles/tripleo-collect-logs/scripts = scripts/*
     usr/local/share/ansible/roles/tripleo-collect-logs/tasks = tasks/*
     usr/local/share/ansible/roles/tripleo-collect-logs/templates = templates/*
     usr/local/share/ansible/roles/tripleo-collect-logs/tests = tests/*
     usr/local/share/ansible/roles/tripleo-collect-logs/vars = vars/*
+    usr/local/share/ansible/roles/tripleo-collect-logs/ = doc-requirements.txt
 
 [wheel]
 universal = 1

tasks/create-docs.yml

@@ -0,0 +1,41 @@
+---
+
+- block:
+    - name: Ensure required python packages are installed
+      pip:
+        requirements: "{{ local_working_dir }}/usr/local/share/ansible/roles/tripleo-collect-logs/doc-requirements.txt"
+
+    - name: Unarchive shell scripts
+      shell: >
+        gunzip "{{ artcl_collect_dir }}/undercloud/home/stack/{{ item }}.sh.gz";
+      with_items: "{{ artcl_create_docs_payload.included_deployment_scripts }}"
+      ignore_errors: yes
+      when:  artcl_gzip_only|bool
+
+
+    - name: Generate rST docs from scripts and move to Sphinx src dir
+      shell: >
+         awk -f "{{ local_working_dir }}/usr/local/share/ansible/roles/tripleo-collect-logs/scripts/doc_extrapolation.awk" \
+           "{{ artcl_collect_dir }}/undercloud/home/stack/{{ item }}.sh" > \
+           "{{ artcl_docs_source_dir }}/{{ item }}.rst"
+      with_items: "{{ artcl_create_docs_payload.included_deployment_scripts }}"
+
+    - name: Fetch static rST docs to include in output docs
+      shell: >
+        cp "{{ artcl_docs_source_dir }}/../static/{{ item }}.rst" "{{ artcl_docs_source_dir }}"
+      with_items: "{{ artcl_create_docs_payload.included_static_docs }}"
+
+    - name: Generate fresh index.rst for Sphinx
+      template:
+        src: index.rst.j2
+        dest: "{{ artcl_docs_source_dir }}/index.rst"
+        force: yes
+
+    - name: Build docs with Sphinx
+      shell: >
+        sphinx-build -b html "{{ artcl_docs_source_dir }}" \
+          "{{ artcl_docs_build_dir }}" &> "{{ local_working_dir }}/sphinx_build.log"
+
+  delegate_to: localhost
+  run_once: true
+  when: artcl_gen_docs|bool

tasks/main.yml

@@ -4,5 +4,8 @@
 - include: collect.yml
   when: artcl_collect|bool
 
+- include: create-docs.yml
+  when: artcl_gen_docs|bool
+
 - include: publish.yml
   when: artcl_publish|bool

templates/index.rst.j2

@@ -0,0 +1,15 @@
+Welcome to |project| Documentation:
+===================================
+
+--------
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   Requirements and Primer <index>
+{% for doc in artcl_create_docs_payload.table_of_contents %}
+   {{ doc }}
+{% endfor %}