Improve patrole core documentation
Updates patrole's current documentation with improved formatting.
Also updates many sections to add more clarity and detail.
Change-Id: Idebe341e2fcb0ee04db979d41df9bef5395af1b5
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fbe592c..35e8439 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,7 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to patrole's documentation!
+Patrole - an OpenStack Tempest Plugin for RBAC Testing
========================================================
Contents:
@@ -22,4 +22,3 @@
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
-
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 76064f1..b532d63 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -3,24 +3,24 @@
============
Installation Information
-########################
+========================
At the command line::
- $ pip install patrole
+ $ sudo pip install patrole
Or, if you have virtualenvwrapper installed::
$ mkvirtualenv patrole
- $ pip install patrole
+ $ sudo pip install patrole
Or to install from the source::
$ navigate to patrole directory
- $ pip install -e .
+ $ sudo pip install -e .
Configuration Information
-#########################
+=========================
tempest.conf
++++++++++++
@@ -28,25 +28,25 @@
To run the RBAC tempest api test, you have to make the following changes to
the tempest.conf file.
-#. [auth] section updates ::
+#. ``auth`` section updates ::
- # Allows test cases to create/destroy projects and users. This option
- # requires that OpenStack Identity API admin credentials are known. If
- # false, isolated test cases and parallel execution, can still be
- # achieved configuring a list of test accounts (boolean value)
- use_dynamic_credentials = True
+ # Allows test cases to create/destroy projects and users. This option
+ # requires that OpenStack Identity API admin credentials are known. If
+ # false, isolated test cases and parallel execution, can still be
+ # achieved configuring a list of test accounts (boolean value)
+ use_dynamic_credentials = True
-#. [rbac] section updates ::
+#. ``rbac`` section updates ::
- # The role that you want the RBAC tests to use for RBAC testing
- # This needs to be edited to run the test as a different role.
- rbac_test_role = _member_
+ # The role that you want the RBAC tests to use for RBAC testing
+ # This needs to be edited to run the test as a different role.
+ rbac_test_role = _member_
- # Enables RBAC Tempest tests if set to True. Otherwise, they are
- # skipped.
- enable_rbac = True
+ # Enables RBAC Tempest tests if set to True. Otherwise, they are
+ # skipped.
+ enable_rbac = True
- # If set to true, tests throw a RbacParsingException for policies
- # not found in the policy.json. Otherwise, they throw a
- # skipException.
- strict_policy_check = False
+ # If set to true, tests throw a RbacParsingException for policies
+ # not found in the policy.json. Otherwise, they throw a
+ # skipException.
+ strict_policy_check = False
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 5d6c0b9..c2fc6d3 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -1,10 +1,36 @@
+..
+
========
Usage
========
-To use run patrole tests in Tempest::
+Running Patrole Tests in Tempest
+================================
- If patrole is installed correctly tests are run like any others.
+If Patrole is installed correctly, then the API tests can be executed
+from inside the tempest root directory as follows: ::
- To change the role that the patrole tests are being run as edit rbac_role
- in the rbac section of tempest.conf.
+ tox -eall-plugin -- patrole_tempest_plugin.tests.api
+
+To execute patrole tests for a specific module, run: ::
+
+ tox -eall-plugin -- patrole_tempest_plugin.tests.api.compute
+
+To change the role that the patrole tests are being run as, edit
+``rbac_test_role`` in the ``rbac`` section of tempest.conf: ::
+
+ [rbac]
+ rbac_test_role = Member
+ ...
+
+.. note::
+
+ The ``rbac_test_role`` is service-specific. Member, for example,
+ is an arbitrary role, but by convention is used to designate the default
+ non-admin role in the system. Most patrole tests should be run with
+ **admin** and **Member** roles. However, some services, like Heat, take
+ advantage of a role called **heat_stack_user**, as it appears frequently
+ in Heat's policy.json.
+
+For more information about the Member role,
+please see: `<https://ask.openstack.org/en/question/4759/member-vs-_member_/>`__.