Quick documentation content reorganization

This patch organizes better the content of the documentation files in order
to render it clearer and better.

Change-Id: I5a00e854198fc5429db0353b490dc07192183476

CONTRIBUTING.rst

@@ -1,17 +1,52 @@
-If you would like to contribute to the development of OpenStack, you must
+For general information on contributing to OpenStack, please check out the
-follow the steps in this page:
+`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
+It covers all the basics that are common to all OpenStack projects: the accounts
+you need, the basics of interacting with our Gerrit review system, how we
+communicate as a community, etc.
 
-   https://docs.openstack.org/infra/manual/developers.html
+The information below will cover the project specific information you need to get started with TripleO.
 
-If you already have a good understanding of how the system works and your
+Documentation
-OpenStack accounts are set up, you can skip to the development workflow
+=============
-section of this documentation to learn how changes to OpenStack should be
+Documentation for the TripleO project can be found `here <https://docs.openstack.org/tripleo-docs/latest/index.html>`_
-submitted for review via the Gerrit tool:
 
-   https://docs.openstack.org/infra/manual/developers.html#development-workflow
+Communication
+=============
+* IRC channel ``#tripleo`` at FreeNode
+* Mailing list (prefix subjects with ``[tripleo][validations]`` for faster responses)
+  http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
 
-Pull requests submitted through GitHub will be ignored.
+Contacting the Core Team
+========================
+Please refer to the `TripleO Core Team
+<https://review.opendev.org/#/admin/groups/190,members>`_ contacts.
 
-Bugs should be filed on Storyboard, not GitHub:
+Bug Tracking
+=============
+We track our tasks in `Launchpad <https://bugs.launchpad.net/tripleo/+bugs?field.tag=validations>`_ and in
+`StoryBoard <https://storyboard.openstack.org/#!/project_group/76>`_
 
-   https://storyboard.openstack.org/#!/project/openstack/tripleo-validations
+Reporting a Bug
+===============
+You found an issue and want to make sure we are aware of it? You can do so on
+`Launchpad <https://bugs.launchpad.net/tripleo/+filebug>`__. Please, add the
+validations tag to your bug.
+
+More info about Launchpad usage can be found on `OpenStack docs page
+<https://docs.openstack.org/contributors/common/task-tracking.html#launchpad>`_
+
+Getting Your Patch Merged
+=========================
+All changes proposed to the TripleO requires two ``Code-Review +2`` votes from
+TripleO core reviewers before one of the core reviewers can approve patch by
+giving ``Workflow +1`` vote.
+
+Project Team Lead Duties
+========================
+All common PTL duties are enumerated in the `PTL guide
+<https://docs.openstack.org/project-team-guide/ptl.html>`_.
+
+The Release Process for TripleO is documented in `Release Management
+<https://docs.openstack.org/tripleo-docs/latest/developer/release.html>`_.
+
+Documentation for the TripleO project can be found `here <https://docs.openstack.org/tripleo-docs/latest/index.html>`_

README.rst

@@ -1,7 +1,3 @@
-===================
-TripleO Validations
-===================
-
 .. image:: https://governance.openstack.org/tc/badges/tripleo-validations.svg
     :target: https://governance.openstack.org/tc/reference/tags/index.html
 
@@ -15,8 +11,9 @@ prevent field engineers from wasting time on misconfiguration or hardware
 issues in their environments.
 
 All validations are written in Ansible and are written in a way that's
-consumable by the `Mistral validation framework`_ or by Ansible directly.
+consumable by the `Validation Framework Command Line Interface (CLI)
-They are available independently from the UI or the command line client.
+<https://docs.openstack.org/validations-libs/latest/reference/api/validations_libs.cli.html>`_
+or by Ansible directly.
 
 * Free software: Apache license
 * Documentation: https://docs.openstack.org/tripleo-validations/latest/
@@ -24,4 +21,3 @@ They are available independently from the UI or the command line client.
 * Source: https://opendev.org/openstack/tripleo-validations
 * Bugs: https://storyboard.openstack.org/#!/project/openstack/tripleo-validations
 
-.. _Mistral validation framework: https://specs.openstack.org/openstack/tripleo-specs/specs/newton/validations.html

doc/source/_exts/generate_validations_doc.py

@@ -138,16 +138,13 @@ Role documentation
 def build_groups_detail(groups):
     entries = [
         """
-{group}
+**{group}**:
-{adornment}
 
-{desc}
+*{desc}*
 
 .. include:: {link}
-
 """
         .format(group=grp.capitalize(),
-                adornment=(len(grp) * '~'),
                 link="validations-{}.rst".format(grp),
                 desc=desc[0].get('description', None),
                 )

doc/source/contributing.rst

@@ -1,4 +0,0 @@
-============
-Contributing
-============
-.. include:: ../../CONTRIBUTING.rst

doc/source/contributing/contributing.rst

@@ -0,0 +1,5 @@
+============================
+So You Want to Contribute...
+============================
+
+.. include:: ../../../CONTRIBUTING.rst

doc/source/contributing/developer_guide.rst

@@ -1,60 +1,5 @@
-========================
+Developer's Guide
-Team and repository tags
+=================
-========================
-
-.. image:: https://governance.openstack.org/tc/badges/tripleo-validations.svg
-    :target: https://governance.openstack.org/tc/reference/tags/index.html
-
-.. Change things from this point on
-
-TripleO Validations
-===================
-
-A collection of Ansible roles and playbooks to detect and report potential
-issues during TripleO 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.
-
-All validations are written in Ansible and are written in a way that's
-consumable by the `Mistral validation framework
-<https://review.opendev.org/#/c/255792/>`_ or by Ansible directly. They are
-available independently from the UI or the command line client.
-
-* Free software: Apache license
-* Documentation: https://docs.openstack.org/tripleo-validations/latest/
-* Release notes: https://docs.openstack.org/releasenotes/tripleo-validations/
-* Source: https://opendev.org/openstack/tripleo-validations
-* Bugs: https://storyboard.openstack.org/#!/project/openstack/tripleo-validations
-
-Prerequisites
--------------
-
-The TripleO validations require Ansible 2.7 or above::
-
-    $ sudo pip install 'ansible>=2.7'
-
-Existing validations
---------------------
-
-Here are all the validations that currently exist. They're grouped by
-the deployment stage they're should be run on.
-
-Validations can belong to multiple groups.
-
-.. include:: validations-groups.rst
-
-To add a new group, you will need to edit the ``groups.yaml`` file located in
-the root of the TripleO Validations directory::
-
-    $ [vim|emacs] groups.yaml
-    ...
-    pre-update:
-      - description: >-
-          Validations which try to validate your OpenStack deployment before you
-          update it.
-    ...
 
 And a new entry in the sphinx documentation index::
 
@@ -76,7 +21,7 @@ Writing Validations
 -------------------
 
 All validations are written in standard Ansible with a couple of extra
-meta-data to provide information to the Mistral validation framework.
+meta-data to provide information to the validation framework.
 
 For people not familiar with Ansible, get started with their `excellent
 documentation <https://docs.ansible.com/ansible/>`_.
@@ -276,7 +221,7 @@ Learn more at the `Ansible documentation page about writing custom modules
 <https://docs.ansible.com/ansible/developing_modules.html>`__.
 
 Running a validation
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 Running the validations require ansible and a set of nodes to run them against.
 These nodes need to be reachable from the operator's machine and need to have
@@ -484,7 +429,7 @@ And that's it! The validation is now finished and you can start using it in
 earnest.
 
 Create a new role with automation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 The role addition process is also automated using ansible. If ansible is
 available on the development workstation change directory to the root of
@@ -504,8 +449,8 @@ When the role is ready for CI, add a **job** entry into the
     - job:
         files:
         - ^roles/${NEWROLENAME}/.*
-        name: tripleo-validations-centos-7-molecule-${NEWROLENAME}
+        name: tripleo-validations-centos-8-molecule-${NEWROLENAME}
-        parent: tripleo-validations-centos-7-base
+        parent: tripleo-validations-centos-8-base
         vars:
           tripleo_validations_role_name: ${NEWROLENAME}
 
@@ -518,10 +463,10 @@ of the `molecule.yaml` file.
     - project:
         check:
           jobs:
-            - tripleo-validations-centos-7-molecule-${NEWROLENAME}
+            - tripleo-validations-centos-8-molecule-${NEWROLENAME}
         gate:
           jobs:
-            - tripleo-validations-centos-7-molecule-${NEWROLENAME}
+            - tripleo-validations-centos-8-molecule-${NEWROLENAME}
 
 
 Finally add a role documentation file at
@@ -531,7 +476,7 @@ the molecule playbook, or playbooks, used to test the role, which is noted
 as an "example" playbook.
 
 Local testing of new roles
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Local testing of new roles can be done in any number of ways, however,
 the easiest way is via the script `run-local-test` on a *CentOS 8* machaine.

doc/source/groups.rst

@@ -0,0 +1,42 @@
+About Group
+===========
+
+For now, the validations are grouped by the deployment stage they should be run
+on. A validation can belong to multiple groups.
+
+Adding a new group
+------------------
+
+To add a new group, you will need to edit the ``groups.yaml`` file located in
+the root of the TripleO Validations directory::
+
+    $ [vim|emacs] groups.yaml
+    ...
+    pre-update:
+      - description: >-
+          Validations which try to validate your OpenStack deployment before you
+          update it.
+    ...
+
+And a new entry in the sphinx documentation index::
+
+    $ [vim|emacs] doc/source/index.rst
+    ...
+    Existing validations:
+
+    .. toctree::
+      :maxdepth: 2
+
+      validations-no-op-details
+      validations-prep-details
+      validations-pre-introspection-details
+      validations-pre-deployment-details
+      validations-post-deployment-details
+    ...
+
+Group list
+----------
+
+Here is a list of groups and their associated validations.
+
+.. include:: validations-groups.rst

doc/source/index.rst

@@ -3,21 +3,42 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+===============================================
 Welcome to tripleo-validations's documentation!
 ===============================================
 
-Contents:
+Introduction
+============
+
+.. include:: ../../README.rst
+
+Installation Guide
+==================
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
-   contributing
-   roles
-   modules
 
-Existing validations:
+Contributing
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   contributing/contributing
+   contributing/developer_guide
+
+Existing Groups
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   groups
+
+Existing Validations
+====================
 
 .. toctree::
    :maxdepth: 2
@@ -49,6 +70,15 @@ Existing validations:
    validations-post-update-details
    validations-backup-and-restore-details
 
+Existing Roles and Modules
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   roles
+   modules
+
 
 Indices and tables
 ==================

doc/source/installation.rst

@@ -1,12 +1,13 @@
-============
+Prerequisites
+=============
+
+The TripleO validations requires Ansible ">=2.8,<2.0.0"::
+
+    $ sudo pip install 'ansible>=2.8,<2.10.0'
+
 Installation
 ============
 
 At the command line::
 
-    $ pip install tripleo-validations
+    $ python3 -m pip install tripleo-validations
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv tripleo-validations
-    $ pip install tripleo-validations