From 3fe95b2aebde226bab0d710885f60a1862499b16 Mon Sep 17 00:00:00 2001
From: Lance Bragstad <lbragstad@gmail.com>
Date: Fri, 1 Jun 2018 22:07:34 +0000
Subject: [PATCH] Add CLI usage documentation

This commit adds usage and examples for generating sample policy
files and listing redundant policy rules.

Change-Id: I2ff00a0a038fde5596ec2fe35de1b7647efcbb9c
Closes-Bug: 1741073
---
 doc/source/cli/index.rst                      | 64 +++++++++++++++++++
 .../expand-cli-docs-02c2f13adbe251c0.yaml     |  6 ++
 2 files changed, 70 insertions(+)
 create mode 100644 releasenotes/notes/expand-cli-docs-02c2f13adbe251c0.yaml

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index 08b56c9f..87f9fcfc 100644
--- a/doc/source/cli/index.rst
+++ b/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
diff --git a/releasenotes/notes/expand-cli-docs-02c2f13adbe251c0.yaml b/releasenotes/notes/expand-cli-docs-02c2f13adbe251c0.yaml
new file mode 100644
index 00000000..01759910
--- /dev/null
+++ b/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.