From 082d38eaefa11b116a303725619e555c66362fe2 Mon Sep 17 00:00:00 2001 From: Harry Rybacki Date: Thu, 4 Aug 2016 11:19:40 -0400 Subject: [PATCH] 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 | 62 +++++++- defaults/main.yml | 5 + doc-requirements.txt | 5 + docs/source/_custom/custom.css | 226 ++++++++++++++++++++++++++++ docs/source/_custom/rdo_styling.css | 208 +++++++++++++++++++++++++ docs/source/_templates/layout.html | 1 + docs/source/conf.py | 127 ++++++++++++++++ docs/static/env-setup-virt.rst | 65 ++++++++ scripts/doc_extrapolation.awk | 42 ++++++ setup.cfg | 3 + tasks/create-docs.yml | 41 +++++ tasks/main.yml | 3 + templates/index.rst.j2 | 15 ++ 13 files changed, 797 insertions(+), 6 deletions(-) create mode 100644 doc-requirements.txt create mode 100644 docs/source/_custom/custom.css create mode 100644 docs/source/_custom/rdo_styling.css create mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/conf.py create mode 100644 docs/static/env-setup-virt.rst create mode 100644 scripts/doc_extrapolation.awk create mode 100644 tasks/create-docs.yml create mode 100644 templates/index.rst.j2 diff --git a/README.md b/README.md index dd871f6..15a1f67 100644 --- a/README.md +++ b/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 - one in `artcl_collect_dir`, when false, a tar.gz file will contain all the +* `artcl_gzip_only`: false/true -- When true, gathered files are gzipped one + 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 `## ` 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 ------- diff --git a/defaults/main.yml b/defaults/main.yml index de9870a..39494fa 100644 --- a/defaults/main.yml +++ b/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" diff --git a/doc-requirements.txt b/doc-requirements.txt new file mode 100644 index 0000000..dfd51f7 --- /dev/null +++ b/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 diff --git a/docs/source/_custom/custom.css b/docs/source/_custom/custom.css new file mode 100644 index 0000000..7aa7f8d --- /dev/null +++ b/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; +} diff --git a/docs/source/_custom/rdo_styling.css b/docs/source/_custom/rdo_styling.css new file mode 100644 index 0000000..df9be63 --- /dev/null +++ b/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; +} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000..7170ae5 --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1 @@ +{% extends "!layout.html" %} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..33d598c --- /dev/null +++ b/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) diff --git a/docs/static/env-setup-virt.rst b/docs/static/env-setup-virt.rst new file mode 100644 index 0000000..6160ab3 --- /dev/null +++ b/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 diff --git a/scripts/doc_extrapolation.awk b/scripts/doc_extrapolation.awk new file mode 100644 index 0000000..b1d91ec --- /dev/null +++ b/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 `## ` 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) +} diff --git a/setup.cfg b/setup.cfg index cea83fb..af31067 100644 --- a/setup.cfg +++ b/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 diff --git a/tasks/create-docs.yml b/tasks/create-docs.yml new file mode 100644 index 0000000..b68f73c --- /dev/null +++ b/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 diff --git a/tasks/main.yml b/tasks/main.yml index 719380d..603434c 100644 --- a/tasks/main.yml +++ b/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 diff --git a/templates/index.rst.j2 b/templates/index.rst.j2 new file mode 100644 index 0000000..94ebbec --- /dev/null +++ b/templates/index.rst.j2 @@ -0,0 +1,15 @@ +Welcome to |project| Documentation: +=================================== + +-------- +Contents +-------- + +.. toctree:: + :maxdepth: 2 + :numbered: + + Requirements and Primer +{% for doc in artcl_create_docs_payload.table_of_contents %} + {{ doc }} +{% endfor %}