Docs: Add requirements authority module to documentation
This patchset includes documentation on the rbac_authority
and the requirements_authority modules. In addition,
the documentation for the policy_authority module is
expanded. All 3 modules are explained together, explaining
that the rbac_authority module contains an abstract
class consumed by the classes in the other two modules.
The use cases for each validation approach is also included
in the documentation.
Finally, some documentation syntax issues are corrected.
Change-Id: I33bbe2da67683faafd0749b687b99237ac815009
diff --git a/etc/patrole.conf.sample b/etc/patrole.conf.sample
index 518d38a..8e7931b 100644
--- a/etc/patrole.conf.sample
+++ b/etc/patrole.conf.sample
@@ -29,9 +29,10 @@
#
# This option determines whether Patrole should run against a
# ``custom_requirements_file`` which defines RBAC requirements. The
-# purpose of setting this flag to True is to verify that RBAC policy
+# purpose of setting this flag to ``True`` is to verify that RBAC
+# policy
# is in accordance to requirements. The idea is that the
-# ``custom_requirements_file`` perfectly defines what the RBAC
+# ``custom_requirements_file`` precisely defines what the RBAC
# requirements are.
#
# Here are the possible outcomes when running the Patrole tests
@@ -57,28 +58,32 @@
# file must be located on the same host that Patrole runs on. The YAML
# file should be written as follows:
#
-# ```
-# <service_foo>:
-# <api_action_x>:
-# - <allowed_role_a>
-# - <allowed_role_b>
-# - <allowed_role_c>
-# <api_action_y>:
-# - <allowed_role_d>
-# - <allowed_role_e>
-# <service_bar>:
-# <api_action_z>:
-# - <allowed_role_b>
-# ```
+# .. code-block:: yaml
+#
+# <service_foo>:
+# <api_action_a>:
+# - <allowed_role_1>
+# - <allowed_role_2>
+# - <allowed_role_3>
+# <api_action_b>:
+# - <allowed_role_2>
+# - <allowed_role_4>
+# <service_bar>:
+# <api_action_c>:
+# - <allowed_role_3>
#
# Where:
#
-# service = the service that is being tested (Cinder, Nova, etc.)
+# service = the service that is being tested (Cinder, Nova, etc.).
+#
# api_action = the policy action that is being tested. Examples:
-# - volume:create
-# - os_compute_api:servers:start
-# - add_image
-# allowed_role = the Keystone role that is allowed to perform the API.
+#
+# * volume:create
+# * os_compute_api:servers:start
+# * add_image
+#
+# allowed_role = the ``oslo.policy`` role that is allowed to perform
+# the API.
# (string value)
#custom_requirements_file = <None>