Add plugin documentation

This change adds documentation for all of the plugins currently
found in the tripleo-ansible repo. This will provide for much
greater visability into what we're providing and will allow
users and developers to better understand how to consume
the available resources.

Change-Id: I2f5813095cbadd999bc68235278a9da1f883e01e
Signed-off-by: Kevin Carter <kecarter@redhat.com>

doc/source/_exts/ansible-module-autodoc.py

@@ -0,0 +1,175 @@
+# Copyright 2019 Red Hat, Inc.
+# All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+
+import imp
+import os
+
+from docutils import core
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.parsers import rst
+from docutils.writers.html4css1 import Writer
+
+from sphinx import addnodes
+
+import yaml
+
+
+class AnsibleAutoPluginDirective(Directive):
+    directive_name = "ansibleautoplugin"
+    has_content = True
+    option_spec = {
+        'module': rst.directives.unchanged_required,
+        'documentation': rst.directives.unchanged,
+        'examples': rst.directives.unchanged
+    }
+
+    @staticmethod
+    def _render_html(source):
+        return core.publish_parts(
+            source=source,
+            writer=Writer(),
+            writer_name='html',
+            settings_overrides={'no_system_messages': True}
+        )
+
+    def make_node(self, title, contents, content_type=None):
+        section = nodes.section(
+            title,
+            nodes.title(text=title),
+            ids=[nodes.make_id(__file__)],
+        )
+
+        if not content_type:
+            # Doc section
+            for content in contents['docs']:
+                for paragraph in content.split('\n'):
+                    retnode = nodes.paragraph()
+                    html = self._render_html(source=paragraph)
+                    retnode += nodes.raw('', html['body'], format='html')
+                    section.append(retnode)
+
+            # Options Section
+            options_list = nodes.field_list()
+            options_section = nodes.section(
+                'Options',
+                nodes.title(text='Options'),
+                ids=[nodes.make_id(__file__)],
+            )
+            for key, value in contents['options'].items():
+                body = nodes.field_body()
+                if isinstance(value['description'], list):
+                    for desc in value['description']:
+                        html = self._render_html(source=desc)
+                        body.append(
+                            nodes.raw('', html['body'], format='html')
+                        )
+                else:
+                    html = self._render_html(source=value['description'])
+                    body.append(
+                        nodes.raw('', html['body'], format='html')
+                    )
+
+                field = nodes.field()
+                field.append(nodes.field_name(text=key))
+                field.append(body)
+                options_list.append(field)
+            else:
+                options_section.append(options_list)
+                section.append(options_section)
+
+            # Authors Section
+            authors_list = nodes.field_list()
+            authors_section = nodes.section(
+                'Authors',
+                nodes.title(text='Authors'),
+                ids=[nodes.make_id(__file__)],
+            )
+            field = nodes.field()
+            field.append(nodes.field_name(text=''))
+            for author in contents['author']:
+                body = nodes.field_body()
+                html = self._render_html(source=author)
+                body.append(
+                    nodes.raw('', html['body'], format='html')
+                )
+                field.append(body)
+            else:
+                authors_list.append(field)
+                authors_section.append(authors_list)
+                section.append(authors_section)
+
+        elif content_type == 'yaml':
+            for content in contents:
+                retnode = nodes.literal_block(text=content)
+                retnode['language'] = 'yaml'
+                section.append(retnode)
+
+        return section
+
+    def load_module(self, filename):
+        return imp.load_source('__ansible_module__', filename)
+
+    def build_documentation(self, module):
+        docs = yaml.safe_load(module.DOCUMENTATION)
+        doc_data = dict()
+        doc_data['docs'] = docs['description']
+        doc_data['author'] = docs.get('author', list())
+        doc_data['options'] = docs.get('options', dict())
+        return doc_data
+
+    def build_examples(self, module):
+        examples = yaml.safe_load(module.EXAMPLES)
+        return_examples = list()
+        for example in examples:
+            return_examples.append(
+                yaml.safe_dump([example], default_flow_style=False)
+            )
+        return return_examples
+
+    def run(self):
+        module = self.load_module(filename=self.options['module'])
+        return_data = list()
+        if self.options.get('documentation'):
+            docs = self.build_documentation(module=module)
+            return_data.append(
+                self.make_node(
+                    title="Module Documentation",
+                    contents=docs
+                )
+            )
+
+        if self.options.get('examples'):
+            examples = self.build_examples(module=module)
+            return_data.append(
+                self.make_node(
+                    title="Example Tasks",
+                    contents=examples,
+                    content_type='yaml'
+                )
+            )
+
+        return return_data
+
+
+def setup(app):
+    classes = [
+        AnsibleAutoPluginDirective,
+    ]
+    for directive_class in classes:
+        app.add_directive(directive_class.directive_name, directive_class)
+
+    return {'version': '0.1'}

doc/source/conf.py

@@ -26,12 +26,14 @@ sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'openstackdocstheme',
-    'sphinx.ext.autodoc'
+    'sphinx.ext.autodoc',
+    'ansible-module-autodoc'
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
+# autodoc_mock_imports = ["django"]
 
 # The suffix of source filenames.
 source_suffix = '.rst'

doc/source/contributing.rst

@@ -144,3 +144,34 @@ test being executed and running the environment.
 .. code-block:: console
 
     (test-python) $ molecule --debug test
+
+
+Contributing plugins
+~~~~~~~~~~~~~~~~~~~~
+
+All plugins contributed to the TripleO-Ansible can be found in the
+`tripleo_ansible/ansible_plugins` directory, from the root of this project.
+When contributing a plugin, make sure to also add documentation in the
+`doc/source/modules` folder. All documentation added to this folder will be
+automatically indexed and rendered via `sphinx`.
+
+If a contributed plugin is following the Ansible practice of placing
+documentation within the plugin itself, the following snippet can be used in a
+sphinx template to auto-render the in-code documentation.
+
+.. code-block:: rst
+
+    .. ansibleautoplugin::
+       :module: tripleo_ansible/ansible_plugins/${DIRECTORY}/${PLUGINFILE}
+       :documentation: true
+       :examples: true
+
+The snippet can take two options, `documentation` and `examples`. If a given
+plugin does not have either of these in-code documentation objects,
+documentation for either type can be disabled by omitting the option.
+
+.. code-block:: rst
+
+    .. ansibleautoplugin::
+       :module: tripleo_ansible/ansible_plugins/${DIRECTORY}/${PLUGINFILE}
+       :documentation: true

doc/source/index.rst

@@ -15,6 +15,7 @@ Contents:
    contributing
    usage
    roles
+   modules
 
 Indices and tables
 ==================

doc/source/modules.rst

@@ -0,0 +1,9 @@
+Documented modules in TripleO-Ansible
+=====================================
+
+Contents:
+
+.. toctree::
+   :glob:
+
+   modules/*

doc/source/modules/action-package.rst

@@ -0,0 +1,14 @@
+================
+Module - package
+================
+
+
+This module provides for the following ansible plugin:
+
+    * package
+
+
+.. ansibleautoplugin::
+   :module: tripleo_ansible/ansible_plugins/action/package.py
+   :documentation: true
+   :examples: true

doc/source/modules/calllback-json_error.rst

@@ -0,0 +1,13 @@
+===================
+Module - json_error
+===================
+
+
+This module provides for the following ansible plugin:
+
+    * json_error
+
+
+.. ansibleautoplugin::
+   :module: tripleo_ansible/ansible_plugins/callback/json_error.py
+   :documentation: true

doc/source/modules/modules-podman_container.rst

@@ -0,0 +1,14 @@
+=========================
+Module - podman_container
+=========================
+
+
+This module provides for the following ansible plugin:
+
+    * podman_container
+
+
+.. ansibleautoplugin::
+   :module: tripleo_ansible/ansible_plugins/modules/podman_container.py
+   :documentation: true
+   :examples: true

doc/source/modules/modules-podman_image.rst

@@ -0,0 +1,14 @@
+=====================
+Module - podman_image
+=====================
+
+
+This module provides for the following ansible plugin:
+
+    * podman_image
+
+
+.. ansibleautoplugin::
+   :module: tripleo_ansible/ansible_plugins/modules/podman_image.py
+   :documentation: true
+   :examples: false

doc/source/modules/modules-podman_image_facts.rst

@@ -0,0 +1,14 @@
+===========================
+Module - podman_image_facts
+===========================
+
+
+This module provides for the following ansible plugin:
+
+    * podman_image_facts
+
+
+.. ansibleautoplugin::
+   :module: tripleo_ansible/ansible_plugins/modules/podman_image_facts.py
+   :documentation: true
+   :examples: true

tox.ini

@@ -95,10 +95,12 @@ commands =
 
 [testenv:docs]
 basepython = python3
-deps = -r{toxinidir}/doc/requirements.txt
+deps =
+  -r{toxinidir}/doc/requirements.txt
+  -r{toxinidir}/molecule-requirements.txt
 commands=
     doc8 doc
-    sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
+    sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html -T
 
 [doc8]
 # Settings for doc8:

tripleo_ansible/ansible_plugins/action/package.py

@@ -20,6 +20,61 @@ import os
 import ansible.plugins.action as action
 
 
+DOCUMENTATION = """
+---
+module: package
+author:
+    - Kevin Carter (@cloudnull)
+version_added: '2.8'
+short_description: Tripleo action plugin to evaluate package installations
+notes: []
+description:
+  - This is an action plugin shim that will intercept the use of
+    the standard package module. The intention of this shim is to ensure the
+    package module respects the option `tripleo_enable_package_install`
+    which is used to control the installation of packages through a
+    deployment.
+
+    This plugin will do nothing if `tripleo_enable_package_install`
+    is unset thereby allowing ansible to function normally. When the global
+    option is present the plugin will evaluate its truthiness and react
+    accordingly.
+
+    * False - No action taken, task will be marked as skipped.
+
+    * True - Package installation happens normally.
+
+    If this module encounters an error while processesing the module will
+    proceed as if the option `tripleo_enable_package_install` is unset which
+    ensures ansible tasks are handled correctly no matter the context in
+    which they are executed.
+
+    Anytime this module results in a "skip" a message will be made available
+    which indicates why it was skipped. Messages will only be visualized
+    when debug mode has been enabled or through registering a variable and
+    using it a task which can print messages; e.g. `debug` or `fail`.
+options:
+  tripleo_enable_package_install:
+    description:
+      - Boolean option to enable or disable package installations. This option
+        can be passed in as a task var, groupvar, or hostvar. This option is
+        **NOT** a module argument.
+    required: True
+    default: True
+"""
+
+
+EXAMPLES = """
+# Run package install
+- name: Run Package Installation
+  package:
+    name: mypackage
+    state: present
+  vars:
+    tripleo_enable_package_install: true
+"""
+
+
 # NOTE(cloudnull): imp is being used because core action plugins are not
 #                  importable in py27. Once we get to the point where we
 #                  no longer support py27 these lines should be converted
@@ -63,32 +118,6 @@ def _bool_set(bool_opt):
 
 
 class ActionModule(PKG.ActionModule):
-    """Tripleo action plugin made to evaluate package installations.
-
-    This is an action plugin shim that will intercept the use of
-    the standard package module. The intention of this shim is to ensure the
-    package module respects the option `tripleo_enable_package_install`
-    which is used to control the installation of packages through a deployment.
-
-    This plugin will do nothing if the option `tripleo_enable_package_install`
-    is unset thereby allowing ansible to function normally. When the global
-    option is present the plugin will evaluate its truthiness and react
-    accordingly.
-
-    * False: No action taken, task will be marked as skipped.
-    * True: Package installation happens normally.
-
-    If this module encounters an error while processesing the module will
-    proceed as if the option `tripleo_enable_package_install` is unset which
-    ensures ansible tasks are handled correctly no matter the context in which
-    they are executed.
-
-    Anytime this module results in a "skip" a message will be made available
-    which indicates why it was skipped. Messages will only be visualized when
-    debug mode has been enabled or through registering a variable and using it
-    a task which can print messages; e.g. `debug` or `fail`.
-    """
-
     def run(self, tmp=None, task_vars=None):
         """Shim for tripleo package operations.