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
This commit is contained in:
Gael Chamoulaud (Strider)
parent
ac70f2cef0
commit
06ce5bf55c
|
|
@ -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
10
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.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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),
|
||||
)
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
============
|
||||
Contributing
|
||||
============
|
||||
.. include:: ../../CONTRIBUTING.rst
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
============================
|
||||
So You Want to Contribute...
|
||||
============================
|
||||
|
||||
.. include:: ../../../CONTRIBUTING.rst
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
==================
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue