Merge "Add CLI usage documentation"

doc/source/cli/index.rst

@@ -50,3 +50,67 @@ with the plain member token
      --policy  /opt/stack/nova/etc/nova/policy.json \
      --access sample_data/auth_v3_token_member.json \
      --rule compute_extension:flavorextraspecs:index
+
+oslopolicy-sample-generator
+===========================
+
+The ``oslopolicy-sample-generator`` command can be used to generate a sample
+policy file based on the default policies in a given namespace. This tool
+requires a namespace to query for policies and supports output in JSON or YAML.
+
+Examples
+--------
+
+To generate sample policies for a namespace called ``keystone``:
+
+.. code-block:: bash
+
+   oslopolicy-sample-generator --namespace keystone
+
+
+To generate sample policies in JSON use:
+
+.. code-block:: bash
+
+   oslopolicy-sample-generator --namespace nova --format json
+
+To generate a sample policy file and output directly to a file:
+
+.. code-block:: bash
+
+   oslopolicy-sample-generator --namespace keystone \
+     --format yaml \
+     --output-file keystone-policy.yaml
+
+Use the following to generate help text for additional options and arguments
+supported by ``oslopolicy-sample-generator``:
+
+.. code-block:: bash
+
+   oslopolicy-sample-generator --help
+
+oslopolicy-list-redundant
+=========================
+
+The ``oslopolicy-list-redundant`` tool is useful for detecting policies that
+are specified in policy files that are the same as the defaults provided by the
+service. Operators can use this tool to find policies that they can remove from
+their policy files, making maintenance easier.
+
+This tool assumes a policy file containing overrides exists and is specified
+through configuration.
+
+Examples
+--------
+
+To list redundant default policies:
+
+.. code-block:: bash
+
+   oslopolicy-list-redundant --namespace keystone --config-dir /etc/keystone
+
+For more information regarding the options supported by this tool:
+
+.. code-block:: bash
+
+   oslopolicy-list-redundant --help

releasenotes/notes/expand-cli-docs-02c2f13adbe251c0.yaml

@@ -0,0 +1,6 @@
+---
+fixes:
+  - |
+    [`bug 1741073 <https://bugs.launchpad.net/oslo.policy/+bug/1741073>`_]
+    Documentation has been improved to include ``oslopolicy-sample-generator``
+    and ``oslopolicy-list-redundant`` usage.