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/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_/>`__.