openstack/tripleo-validations
Code Issues Proposed changes

Quick documentation content reorganization

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

Change-Id: I5a00e854198fc5429db0353b490dc07192183476
This commit is contained in:
Gael Chamoulaud (Strider) 2020-09-30 11:14:30 +02:00
parent ac70f2cef0
commit 06ce5bf55c
No known key found for this signature in database
GPG Key ID: 4119D0305C651D66
9 changed files with 152 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
CONTRIBUTING.rst
View File

@ -1,17 +1,52 @@
If you would like to contribute to the development of OpenStack, you must
follow the steps in this page:
For general information on contributing to OpenStack, please check out the
`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
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:
Documentation
=============
Documentation for the TripleO project can be found `here <https://docs.openstack.org/tripleo-docs/latest/index.html>`_
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>`_

10
README.rst
View File

@ -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.
They are available independently from the UI or the command line client.
consumable by the `Validation Framework Command Line Interface (CLI)
<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

7
doc/source/_exts/generate_validations_doc.py
View File

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

4
doc/source/contributing.rst
View File

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

5
doc/source/contributing/contributing.rst Normal file
View File

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

75
doc/source/readme.rst → doc/source/contributing/developer_guide.rst
View File

@ -1,60 +1,5 @@
========================
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.
...
Developer's Guide
=================
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}
parent: tripleo-validations-centos-7-base
name: tripleo-validations-centos-8-molecule-${NEWROLENAME}
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.

42
doc/source/groups.rst Normal file
View File

@ -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

42
doc/source/index.rst
View File

@ -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
==================

15
doc/source/installation.rst
View File

@ -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
Or, if you have virtualenvwrapper installed::
$ mkvirtualenv tripleo-validations
$ pip install tripleo-validations
$ python3 -m pip install tripleo-validations