Add validation-common documentation structure

The doc structure from validations-libs was transposed
and slightly altered.

Future expansion of documentation is expected.

Change-Id: Ib1043cf1bef5d9b858da8f9a83fbba52bb570b99
Signed-off-by: Gael Chamoulaud (Strider) <gchamoul@redhat.com>
Signed-off-by: Jiri Podivin <jpodivin@redhat.com>

.gitignore

@@ -45,6 +45,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/reference/api/
 
 # pbr generates these
 AUTHORS

.zuul.yaml

@@ -33,6 +33,7 @@
 
 - project:
     templates:
+      - check-requirements
       - openstack-python3-victoria-jobs
       - validations-common-molecule-jobs
     check:
@@ -40,11 +41,18 @@
         - openstack-tox-linters
         - openstack-tox-cover
         - validations-common-functional
+        - openstack-tox-docs: &tripleo-docs
+            files:
+              - ^doc/.*
+              - ^README.rst
     gate:
       jobs:
         - openstack-tox-linters
         - validations-common-functional
-
+        - openstack-tox-docs: *tripleo-docs
+    promote:
+      jobs:
+        - promote-openstack-tox-docs: *tripleo-docs
 - project-template:
     check:
       jobs:

CONTRIBUTING.rst

@@ -0,0 +1,19 @@
+Contributions to validations-common follow guidelines largely similar
+to those of other openstack projects.
+
+If you're interested in contributing to the validations-libs project,
+the following will help get you started:
+
+   https://docs.openstack.org/infra/manual/developers.html
+
+If you already have a good understanding of how the system works and your
+OpenStack accounts are set up, you can skip to the development workflow
+section of this documentation to learn how changes to OpenStack should be
+submitted for review via the Gerrit tool:
+
+   https://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Pull requests submitted through GitHub will be ignored.
+
+Validations are meant to verify functionality of tripleo systems.
+Therefore a special care should be given to testing your code before submitting a review.

README.rst

@@ -2,35 +2,79 @@
 Validations-common
 ==================
 
-A collection of common Ansible libraries and plugins for the Validation
+.. image:: https://governance.openstack.org/tc/badges/validations-common.svg
-Framework
+    :target: https://governance.openstack.org/tc/reference/tags/index.html
+
+.. Change things from this point on
+
+A collection of Ansible roles and playbooks to detect and report potential
+issues during deployments.
+
+The validations will help detect issues early in the deployment process and
+prevent field engineers from wasting time on misconfiguration or hardware
+issues in their environments.
+
+* Free software: Apache_license_
+* Documentation: https://docs.openstack.org/validations-common/latest/
+* Release notes: https://docs.openstack.org/releasenotes/validations-commons/
+* Source: https://opendev.org/openstack/validations-common
+* Bugs - Upstream: https://bugs.launchpad.net/tripleo/+bugs?field.tag=validations
+* Bugs - Downstream: https://bugzilla.redhat.com/buglist.cgi?component=validations-common&product=Red%20Hat%20OpenStack
+
+Installation
+============
+Recommended process
+-------------------
+
+There are several different ways to install validations-common.
+However it is **recommended** to both install and use
+the package inside python virtual environment.
+
+At the command line using `pip`.
+
+.. code-block:: console
+
+    $ pip install validations-common
 
 
-Validations Callbacks
+Or, if you have virtualenvwrapper_ installed.
-=====================
 
-******************
+.. code-block:: console
-http_json callback
-******************
 
-The callback `http_json` sends Validations logs and information to an HTTP
+    $ mkvirtualenv validations-common
-server as a JSON format in order to get caught and analysed with external
+    $ pip install validations-common
-tools for log parsing (as Fluentd or others).
 
-This callback inherits from `validation_json` the format of the logging
+Installation with package manager
-remains the same as the other logger that the Validation Framework is using
+---------------------------------
-by default.
+Alternativelly it is possible to install validations-common using package manager.
 
-To enable this callback, you need to add it to the callback whitelist.
+Such as `yum`...
-Then you need to export your http server url and port::
 
-    export HTTP_JSON_SERVER=http://localhost
+.. code-block:: console
-    export HTTP_JSON_PORT=8989
 
-The callback will post JSON log to the URL provided.
+    $ yum install validations-common
-This repository has a simple HTTP server for testing purpose under::
 
-    tools/http_server.py
 
-The default host and port are localhost and 8989, feel free to adjust those
+or the more modern `dnf`.
-values to your needs.
+
+.. code-block:: console
+
+    $ dnf install validations-common
+
+
+Usage
+=====
+
+Once the validations-common project has been installed,
+navigate to the chosen share path, usually `/usr/share/ansible`
+to access the installed roles, playbooks, and libraries.
+
+While the validations-common can be run by itself,
+it nonetheless depends on Ansible and validations-libs.
+Therefore it isn't recommended to use only validations-common.
+
+The validations included with validations-common are intended to be demonstrations,
+capable of running on most setups. But they are not meant for production environment.
+
+.. _virtualenvwrapper: https://pypi.org/project/virtualenvwrapper/
+.. _Apache_license: http://www.apache.org/licenses/LICENSE-2.0

bindep.txt

@@ -41,4 +41,8 @@ libsemanage-python3 [platform:redhat !platform:rhel-7 !platform:centos-7]
 gzip
 
 # Required to build language docs
-gettext
+gettext             [doc test]
+graphviz            [doc test]
+# libsrvg2 is needed for sphinxcontrib-svg2pdfconverter in docs builds.
+librsvg2-tools      [doc platform:rpm]
+librsvg2-bin        [doc platform:dpkg]

doc/requirements.txt

@@ -0,0 +1,8 @@
+# this is required for the docs build jobs
+sphinx>=2.0.0,!=2.1.0 # BSD
+openstackdocstheme>=2.2.2 # Apache-2.0
+reno>=3.1.0 # Apache-2.0
+sphinxcontrib-apidoc>=0.2.0  # BSD
+doc8>=0.8.0 # Apache-2.0
+bashate>=0.6.0 # Apache-2.0
+six>=1.11.0 # MIT

doc/source/_exts/ansible-autodoc.py

@@ -0,0 +1,384 @@
+# Copyright 2021 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
+
+try:
+    import io
+    StringIO = io.StringIO
+except ImportError:
+    import StringIO
+
+
+class DocYaml:
+    """
+    Wrapper clas around calls to yaml lib.
+    """
+    def _license_filter(self, data):
+        """This will filter out our boilerplate license heading in return data.
+
+        The filter is used to allow documentation we're creating in variable
+        files to be rendered more beautifully.
+        """
+        lines = []
+        mark = True
+        for line in data.splitlines():
+            if '# Copyright' in line:
+                mark = False
+            if mark:
+                lines.append(line)
+            if '# under the License' in line:
+                mark = True
+        return '\n'.join(lines)
+
+    def dump(self, data, stream=None, **kw):
+        if not stream:
+            stream = StringIO()
+        try:
+            yaml.dump(data=data, stream=stream, Dumper=yaml.Dumper, **kw)
+            return self._license_filter(stream.getvalue().strip())
+        finally:
+            stream.close()
+
+    def load(self, data):
+        return yaml.load(data, Loader=yaml.Loader)
+
+DOCYAML = DocYaml()
+
+
+class AnsibleAutoPluginDirective(Directive):
+    directive_name = "ansibleautoplugin"
+    has_content = True
+    option_spec = {
+        'module': rst.directives.unchanged,
+        'role': rst.directives.unchanged,
+        '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 = self._section_block(title=title)
+        if not content_type:
+            # Doc section
+            for content in contents['docs']:
+                for paragraph in content.split('\n'):
+                    retnode = nodes.paragraph()
+                    retnode.append(self._raw_html_block(data=paragraph))
+                    section.append(retnode)
+
+            # Options Section
+            options_list = nodes.field_list()
+            options_section = self._section_block(title='Options')
+            for key, value in contents['options'].items():
+                options_list.append(
+                    self._raw_fields(
+                        data=value['description'],
+                        field_name=key
+                    )
+                )
+            else:
+                options_section.append(options_list)
+                section.append(options_section)
+
+            # Authors Section
+            authors_list = nodes.field_list()
+            authors_list.append(
+                self._raw_fields(
+                    data=contents['author']
+                )
+            )
+            authors_section = self._section_block(title='Authors')
+            authors_section.append(authors_list)
+            section.append(authors_section)
+
+        elif content_type == 'yaml':
+            for content in contents:
+                section.append(
+                    self._literal_block(
+                        data=content,
+                        dump_data=False
+                    )
+                )
+
+        return section
+
+    @staticmethod
+    def load_module(filename):
+        return imp.load_source('__ansible_module__', filename)
+
+    @staticmethod
+    def build_documentation(module):
+        docs = DOCYAML.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
+
+    @staticmethod
+    def build_examples(module):
+        examples = DOCYAML.load(module.EXAMPLES)
+        return_examples = list()
+        for example in examples:
+            return_examples.append(DOCYAML.dump([example]))
+        return return_examples
+
+    def _raw_html_block(self, data):
+        html = self._render_html(source=data)
+        return nodes.raw('', html['body'], format='html')
+
+    def _raw_fields(self, data, field_name=''):
+        body = nodes.field_body()
+        if isinstance(data, list):
+            for item in data:
+                body.append(self._raw_html_block(data=item))
+        else:
+            body.append(self._raw_html_block(data=data))
+
+        field = nodes.field()
+        field.append(nodes.field_name(text=field_name))
+        field.append(body)
+        return field
+
+    @staticmethod
+    def _literal_block(data, language='yaml', dump_data=True):
+        if dump_data:
+            literal = nodes.literal_block(
+                text=DOCYAML.dump(data)
+            )
+        else:
+            literal = nodes.literal_block(text=data)
+        literal['language'] = 'yaml'
+        return literal
+
+    @staticmethod
+    def _section_block(title, text=None):
+        section = nodes.section(
+            title,
+            nodes.title(text=title),
+            ids=[nodes.make_id('-'.join(title))],
+        )
+        if text:
+            section_body = nodes.field_body()
+            section_body.append(nodes.paragraph(text=text))
+            section.append(section_body)
+
+        return section
+
+    def _yaml_section(self, to_yaml_data, section_title, section_text=None):
+        yaml_section = self._section_block(
+            title=section_title,
+            text=section_text
+        )
+        yaml_section.append(self._literal_block(data=to_yaml_data))
+        return yaml_section
+
+    def _run_role(self, role):
+        section = self._section_block(
+            title='Role Documentation',
+            text='Welcome to the "{}" role documentation.'.format(
+                os.path.basename(role)
+            )
+        )
+        defaults_file = os.path.join(role, 'defaults', 'main.yml')
+        if os.path.exists(defaults_file):
+            with open(defaults_file) as f:
+                role_defaults = DOCYAML.load(f.read())
+            section.append(
+                self._yaml_section(
+                    to_yaml_data=role_defaults,
+                    section_title='Role Defaults',
+                    section_text='This section highlights all of the defaults'
+                                 ' and variables set within the "{}"'
+                                 ' role.'.format(
+                                     os.path.basename(role)
+                                 )
+                )
+            )
+
+        vars_path = os.path.join(role, 'vars')
+        if os.path.exists(vars_path):
+            for v_file in os.listdir(vars_path):
+                vars_file = os.path.join(vars_path, v_file)
+                with open(vars_file) as f:
+                    vars_values = DOCYAML.load(f.read())
+                section.append(
+                    self._yaml_section(
+                        to_yaml_data=vars_values,
+                        section_title='Role Variables: {}'.format(v_file)
+                    )
+                )
+
+        test_list = nodes.field_list()
+        test_section = self._section_block(
+            title='Molecule Scenarios',
+            text='Molecule is being used to test the "{}" role. The'
+                 ' following section highlights the drivers in service'
+                 ' and provides an example playbook showing how the role'
+                 ' is leveraged.'.format(
+                     os.path.basename(role)
+                 )
+        )
+        molecule_path = os.path.join(role, 'molecule')
+        if os.path.exists(molecule_path):
+            for test in os.listdir(molecule_path):
+                molecule_section = self._section_block(
+                    title='Scenario: {}'.format(test)
+                )
+                molecule_file = os.path.join(
+                    molecule_path,
+                    test,
+                    'molecule.yml'
+                )
+                with open(molecule_file) as f:
+                    molecule_conf = DOCYAML.load(f.read())
+
+                driver_data = molecule_conf.get('driver')
+                if driver_data:
+                    molecule_section.append(
+                        nodes.field_name(
+                            text='Driver: {}'.format(
+                                driver_data['name']
+                            )
+                        )
+                    )
+
+                    options = driver_data.get('options')
+                    if options:
+                        molecule_section.append(
+                            self._yaml_section(
+                                to_yaml_data=options,
+                                section_title='Molecule Options'
+                            )
+                        )
+
+                provisioner_data = molecule_conf.get('provisioner')
+                if provisioner_data:
+                    inventory = provisioner_data.get('inventory')
+                    if inventory:
+                        molecule_section.append(
+                            self._yaml_section(
+                                to_yaml_data=inventory,
+                                section_title='Molecule Inventory'
+                            )
+                        )
+
+                molecule_playbook_path = os.path.join(
+                    molecule_path,
+                    test,
+                    'converge.yml'
+                )
+                if not os.path.exists(molecule_playbook_path):
+                    molecule_playbook_path = os.path.join(
+                        molecule_path,
+                        test,
+                        'playbook.yml'
+                    )
+                with open(molecule_playbook_path) as f:
+                    molecule_playbook = DOCYAML.load(f.read())
+                molecule_section.append(
+                    self._yaml_section(
+                        to_yaml_data=molecule_playbook,
+                        section_title='Example {} playbook'.format(test)
+                    )
+                )
+                test_list.append(molecule_section)
+            else:
+                test_section.append(test_list)
+                section.append(test_section)
+
+        self.run_returns.append(section)
+
+        # Document any libraries nested within the role
+        library_path = os.path.join(role, 'library')
+        if os.path.exists(library_path):
+            self.options['documentation'] = True
+            self.options['examples'] = True
+            for lib in os.listdir(library_path):
+                if lib.endswith('.py'):
+                    self._run_module(
+                        module=self.load_module(
+                            filename=os.path.join(
+                                library_path,
+                                lib
+                            )
+                        ),
+                        module_title='Embedded module: {}'.format(lib),
+                        example_title='Examples for embedded module'
+                    )
+
+    def _run_module(self, module, module_title="Module Documentation",
+                    example_title="Example Tasks"):
+        if self.options.get('documentation'):
+            docs = self.build_documentation(module=module)
+            self.run_returns.append(
+                self.make_node(
+                    title=module_title,
+                    contents=docs
+                )
+            )
+
+        if self.options.get('examples'):
+            examples = self.build_examples(module=module)
+            self.run_returns.append(
+                self.make_node(
+                    title=example_title,
+                    contents=examples,
+                    content_type='yaml'
+                )
+            )
+
+    def run(self):
+        self.run_returns = list()
+
+        if self.options.get('module'):
+            module = self.load_module(filename=self.options['module'])
+            self._run_module(module=module)
+
+        if self.options.get('role'):
+            self._run_role(role=self.options['role'])
+
+        return self.run_returns
+
+
+def setup(app):
+    classes = [
+        AnsibleAutoPluginDirective,
+    ]
+    for directive_class in classes:
+        app.add_directive(directive_class.directive_name, directive_class)
+
+    return {'version': '0.2'}

doc/source/conf.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# 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 os
+import sys
+
+# Add the project
+sys.path.insert(0, os.path.abspath('../..'))
+# Add the extensions
+sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts'))
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinxcontrib.apidoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autodoc',
+    'openstackdocstheme',
+    'ansible-autodoc'
+]
+
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../validations_common'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = []
+apidoc_separate_modules = True
+
+# openstackdocstheme options
+openstackdocs_repo_name = 'openstack/validations-common'
+openstackdocs_use_storyboard = True
+openstackdocs_bug_project = 'tripleo'
+openstackdocs_bug_tag = 'documentation'
+
+# 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 = ['validations_libs', 'oslotest']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+copyright = u'2021, OpenStack Foundation'
+
+# A list of ignored prefixes for module index sorting.
+modindex_common_prefix = ['validations_common.']
+
+# 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
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'native'
+
+# A list of glob-style patterns that should be excluded when looking for
+# source files. They are matched against the source file names relative to the
+# source directory, using slashes as directory separators on all platforms.
+exclude_patterns = ['']
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+# html_static_path = ['static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'validations-commondoc'
+html_theme = 'openstackdocs'
+
+latex_use_xindy = False
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    (
+        'index',
+        'doc-validations-common.tex',
+        u'Validations Framework Client Documentation',
+        u'OpenStack LLC',
+        'manual'
+    ),
+]

doc/source/contributing.rst

@@ -0,0 +1,28 @@
+============
+Contributing
+============
+
+.. include:: ../../CONTRIBUTING.rst
+
+Contributor License Agreement
+-----------------------------
+
+.. index::
+   single: license; agreement
+
+In order to contribute to the validations-common project, you need to have
+signed OpenStack's contributor's agreement.
+
+.. seealso::
+
+   * https://docs.openstack.org/infra/manual/developers.html
+   * https://wiki.openstack.org/wiki/CLA
+
+Project Hosting Details
+-----------------------
+
+Code Hosting
+    https://opendev.org/openstack/validations-common
+
+Code Review
+    https://review.opendev.org/#/q/status:open+project:openstack/validations-common,n,z

doc/source/index.rst

@@ -0,0 +1,26 @@
+.. validations-common documentation master file, created by
+   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to validations-common documentation!
+============================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   readme
+   installation
+   usage
+   contributing
+   roles
+   modules
+   reference/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

doc/source/installation.rst

@@ -0,0 +1,43 @@
+============
+Installation
+============
+Recommended process
+-------------------
+
+There are several different ways to install validations-common.
+However it is **recommended** to both install and use
+the package inside python virtual environment.
+
+At the command line using `pip`.
+
+.. code-block:: console
+
+    $ pip install validations-common
+
+
+Or, if you have virtualenvwrapper_ installed.
+
+.. code-block:: console
+
+    $ mkvirtualenv validations-common
+    $ pip install validations-common
+
+Installation with package manager
+---------------------------------
+Alternativelly it is possible to install validations-common using package manager.
+
+Such as `yum`...
+
+.. code-block:: console
+
+    $ yum install validations-common
+
+
+or the more modern `dnf`.
+
+.. code-block:: console
+
+    $ dnf install validations-common
+
+
+.. _virtualenvwrapper: https://pypi.org/project/virtualenvwrapper/

doc/source/modules.rst

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

doc/source/modules/modules-advanced_format.rst

@@ -0,0 +1,14 @@
+========================
+Module - advanced_format
+========================
+
+
+This module provides for the following ansible plugin:
+
+    * advanced_format
+
+
+.. ansibleautoplugin::
+   :module: validations_common/library/advanced_format.py
+   :documentation: true
+   :examples: true

doc/source/modules/modules-callbacks-http_json.rst

@@ -0,0 +1,29 @@
+==================
+http_json callback
+==================
+
+The callback http_json sends Validations logs and information to an HTTP
+server as a JSON format in order to get caught and analysed with external
+tools for log parsing (as Fluentd or others).
+
+This callback inherits from validation_json the format of the logging
+remains the same as the other logger that the Validation Framework is using
+by default.
+
+To enable this callback, you need to add it to the callback whitelist.
+Then you need to export your http server url and port.
+
+.. code-block:: console
+
+    export HTTP_JSON_SERVER=http://localhost
+    export HTTP_JSON_PORT=8989
+
+The callback will post JSON log to the URL provided.
+This repository has a simple HTTP server for testing purpose under:
+
+.. code-block:: console
+
+    tools/http_server.py
+
+The default host and port are localhost and 8989, feel free to adjust those
+values to your needs.

doc/source/modules/modules-check_package_update.rst

@@ -0,0 +1,14 @@
+=============================
+Module - check_package_update
+=============================
+
+
+This module provides for the following ansible plugin:
+
+    * check_package_update
+
+
+.. ansibleautoplugin::
+   :module: validations_common/library/check_package_update.py
+   :documentation: true
+   :examples: true

doc/source/modules/modules-haproxy_conf.rst

@@ -0,0 +1,14 @@
+=====================
+Module - haproxy_conf
+=====================
+
+
+This module provides for the following ansible plugin:
+
+    * haproxy_conf
+
+
+.. ansibleautoplugin::
+   :module: validations_common/library/haproxy_conf.py
+   :documentation: true
+   :examples: true

doc/source/modules/modules-hiera.rst

@@ -0,0 +1,14 @@
+==============
+Module - hiera
+==============
+
+
+This module provides for the following ansible plugin:
+
+    * hiera
+
+
+.. ansibleautoplugin::
+   :module: validations_common/library/hiera.py
+   :documentation: true
+   :examples: true

doc/source/modules/modules-reportentry.rst

@@ -0,0 +1,14 @@
+====================
+Module - reportentry
+====================
+
+
+This module provides for the following ansible plugin:
+
+    * reportentry
+
+
+.. ansibleautoplugin::
+   :module: validations_common/library/reportentry.py
+   :documentation: true
+   :examples: true

doc/source/modules/modules-validations_read_ini.rst

@@ -0,0 +1,14 @@
+=============================
+Module - validations_read_ini
+=============================
+
+
+This module provides for the following ansible plugin:
+
+    * validations_read_ini
+
+
+.. ansibleautoplugin::
+   :module: validations_common/library/validations_read_ini.py
+   :documentation: true
+   :examples: true

doc/source/modules/modules-warn.rst

@@ -0,0 +1,14 @@
+=============
+Module - warn
+=============
+
+
+This module provides for the following ansible plugin:
+
+    * warn
+
+
+.. ansibleautoplugin::
+   :module: validations_common/library/warn.py
+   :documentation: true
+   :examples: true

doc/source/readme.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst

doc/source/reference/index.rst

@@ -0,0 +1,8 @@
+============================================
+Full Validations-common Python API Reference
+============================================
+
+.. toctree::
+  :maxdepth: 1
+
+  api/modules

doc/source/roles.rst

@@ -0,0 +1,9 @@
+Documented roles in Validations-Common
+======================================
+
+Contents:
+
+.. toctree::
+   :glob:
+
+   roles/*

doc/source/roles/role-advanced_format_512e_support.rst

@@ -0,0 +1,6 @@
+============================
+advanced_format_512e_support
+============================
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/advanced_format_512e_support

doc/source/roles/role-check_cpu.rst

@@ -0,0 +1,6 @@
+=========
+check_cpu
+=========
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/check_cpu

doc/source/roles/role-check_disk_space.rst

@@ -0,0 +1,6 @@
+================
+check_disk_space
+================
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/check_disk_space

doc/source/roles/role-check_latest_packages_version.rst

@@ -0,0 +1,6 @@
+=============================
+check_latest_packages_version
+=============================
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/check_latest_packages_version

doc/source/roles/role-check_ram.rst

@@ -0,0 +1,6 @@
+=========
+check_ram
+=========
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/check_ram

doc/source/roles/role-check_selinux_mode.rst

@@ -0,0 +1,6 @@
+==================
+check_selinux_mode
+==================
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/check_selinux_mode

doc/source/roles/role-dns.rst

@@ -0,0 +1,6 @@
+===
+dns
+===
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/dns

doc/source/roles/role-haproxy.rst

@@ -0,0 +1,6 @@
+=======
+haproxy
+=======
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/haproxy

doc/source/roles/role-no_op.rst

@@ -0,0 +1,6 @@
+=====
+no_op
+=====
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/no_op

doc/source/roles/role-ntp.rst

@@ -0,0 +1,6 @@
+===
+ntp
+===
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/ntp

doc/source/roles/role-service_status.rst

@@ -0,0 +1,6 @@
+==============
+service_status
+==============
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/service_status

doc/source/roles/role-validate_selinux.rst

@@ -0,0 +1,6 @@
+================
+validate_selinux
+================
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/validate_selinux

doc/source/roles/role-xfs_check_ftype.rst

@@ -0,0 +1,6 @@
+===============
+xfs_check_ftype
+===============
+
+.. ansibleautoplugin::
+   :role: validations_common/roles/xfs_check_ftype

doc/source/usage.rst

@@ -0,0 +1,14 @@
+=====
+Usage
+=====
+
+Once the validations-common project has been installed,
+navigate to the chosen share path, usually `/usr/share/ansible`
+to access the installed roles, playbooks, and libraries.
+
+While the validations-common can be run by itself,
+it nonetheless depends on Ansible and validations-libs.
+Therefore it isn't recommended to use only validations-common.
+
+The validations included with validations-common are intended to be demonstrations,
+capable of running on most setups. But they are not meant for production environment.

setup.cfg

@@ -3,6 +3,7 @@ name = validations-common
 summary = A common Ansible libraries and plugins for the validations framework
 description-file =
     README.rst
+long_description_content_type = text/x-rst
 author = OpenStack
 author-email = openstack-discuss@lists.openstack.org
 home-page = https://opendev.org/openstack/validations-common

tox.ini

@@ -36,6 +36,7 @@ deps =
     -r {toxinidir}/requirements.txt
     -r {toxinidir}/test-requirements.txt
     -r {toxinidir}/molecule-requirements.txt
+    -r {toxinidir}/doc/requirements.txt
 whitelist_externals = bash
 
 [testenv:bindep]
@@ -101,7 +102,7 @@ commands =
     {[testenv:shebangs]commands}
 
 [testenv:releasenotes]
-deps = -r{toxinidir}/doc/requirements.txt
+deps = -r {toxinidir}/doc/requirements.txt
 commands =
     sphinx-build -a -E -W -d releasenotes/build/doctrees --keep-going -b html releasenotes/source releasenotes/build/html
 
@@ -129,6 +130,14 @@ commands=
     sphinx-build -a -E -W -d doc/build/doctrees --keep-going -b html doc/source doc/build/html -T
     doc8 doc
 
+#TODO(jpodivin): pdf-docs don't compile properly
+; [testenv:pdf-docs]
+; whitelist_externals = make
+; deps = {[testenv:docs]deps}
+; commands =
+;   sphinx-build -W -b latex doc/source doc/build/pdf
+;   make -C doc/build/pdf
+
 [doc8]
 # Settings for doc8:
 extensions = .rst

validations_common/__init__.py

@@ -11,7 +11,11 @@
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations
 # under the License.
+"""
+Uses `oslotest`_.
 
+.. _oslotest: https://opendev.org/openstack/oslotest
+"""
 import pbr.version
 
 

validations_common/validation.py

@@ -13,7 +13,11 @@
 #   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #   License for the specific language governing permissions and limitations
 #   under the License.
+"""
+Uses `validations_libs`_.
 
+.. _validations_libs: https://opendev.org/openstack/validations-libs
+"""
 import argparse
 import json
 import logging