Merge "docs: Add separate man page for each CLI tool"3.3.0

11 files changed, 413 insertions, 187 deletions

diff --git a/doc/source/cli/common/default-opts.rst b/doc/source/cli/common/default-opts.rst
new file mode 100644
index 0000000..d439893
--- /dev/null
+++ b/doc/source/cli/common/default-opts.rst
@@ -0,0 +1,19 @@
+.. option:: -h, --help
+
+    Show help message and exit.
+
+.. option:: --config-dir DIR
+
+    Path to a config directory to pull ``*.conf`` files from. This file set is
+    sorted, so as to provide a predictable parse order if individual options
+    are overridden. The set is parsed after the file(s) specified via previous
+    ``--config-file``, arguments hence overridden options in the directory
+    take precedence.
+
+    This option must be set from the command-line.
+
+.. option:: --config-file PATH
+
+    Path to a config file to use. Multiple config files can be specified, with
+    values in later files taking precedence. Defaults to None. This option must
+    be set from the command-line.
diff --git a/doc/source/cli/common/enforcer-opts.rst b/doc/source/cli/common/enforcer-opts.rst
new file mode 100644
index 0000000..ae11354
--- /dev/null
+++ b/doc/source/cli/common/enforcer-opts.rst
@@ -0,0 +1,4 @@
+.. option:: --namespace NAMESPACE
+
+    Option namespace under "oslo.policy.enforcer" in which to look for a
+    ``policy.Enforcer``.
diff --git a/doc/source/cli/common/generator-opts.rst b/doc/source/cli/common/generator-opts.rst
new file mode 100644
index 0000000..b88549f
--- /dev/null
+++ b/doc/source/cli/common/generator-opts.rst
@@ -0,0 +1,3 @@
+.. option:: --output-file OUTPUT_FILE
+
+    Path of the file to write to. Defaults to stdout.
diff --git a/doc/source/cli/common/rule-opts.rst b/doc/source/cli/common/rule-opts.rst
new file mode 100644
index 0000000..3167c7c
--- /dev/null
+++ b/doc/source/cli/common/rule-opts.rst
@@ -0,0 +1,8 @@
+.. option:: --format FORMAT
+
+    Desired format for the output. Allowed values: ``json``, ``yaml``
+
+.. option:: --namespace NAMESPACE
+
+    Option namespace(s) under "oslo.policy.policies" in which to query for
+    options.
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index bef7c99..b8e54d8 100644
--- a/doc/source/cli/index.rst
+++ b/doc/source/cli/index.rst
@@ -5,189 +5,11 @@ Command Line Interface
 This document describes the various command line tools exposed by
 ``oslo.policy`` to manage policies and policy files.
 
-oslopolicy-checker
-==================
-
-Run the command line ``oslopolicy-checker`` to check policy against the
-OpenStack Identity API access information.
-
-Command-line arguments:
-
-* ``--policy POLICY`` path to policy file.
-* ``--access ACCESS`` path to access token file.
-* ``--rule RULE`` (optional) rule to test.  If omitted, tests all rules.
-* ``--is_admin IS_ADMIN`` (optional) set is_admin=True on the credentials.
-
-Sample access tokens are provided in the ``sample_data`` directory.
-
-Examples
---------
-
-Test all of Nova's policy with an admin token
-
-.. code-block:: bash
-
-   tox -e venv -- oslopolicy-checker \
-     --policy  /opt/stack/nova/etc/nova/policy.json
-     --access sample_data/auth_v3_token_admin.json
-
-Test the ``compute_extension:flavorextraspecs:index`` rule in Nova's policy
-with the admin member token and ``is_admin`` set to ``True``
-
-.. code-block:: bash
-
-   tox -e venv -- oslopolicy-checker \
-     --policy  /opt/stack/nova/etc/nova/policy.json \
-     --access sample_data/auth_v3_token_admin.json \
-     --is_admin=true --rule compute_extension:flavorextraspecs:index
-
-Test the ``compute_extension:flavorextraspecs:index`` rule in Nova's policy
-with the plain member token
-
-.. code-block:: bash
-
-   tox -e venv -- oslopolicy-checker \
-     --policy  /opt/stack/nova/etc/nova/policy.json \
-     --access sample_data/auth_v3_token_member.json \
-     --rule compute_extension:flavorextraspecs:index
-
-oslopolicy-policy-generator
-===========================
-
-The ``oslopolicy-policy-generator`` command can be used to generate a policy
-file that shows the effective policy in use. This is generated by merging the
-registered defaults and policies loaded from a configuration file.
-
-Examples
---------
-
-The generate the effective policy file for a namespace called ``keystone``:
-
-.. code-block:: bash
-
-   oslopolicy-policy-generator --namespace keystone
-
-To generate the effective policy file in JSON:
-
-.. code-block:: bash
-
-   oslopolicy-policy-generator --namespace keystone --format json
-
-To generate the effective policy file and output directly to a file:
-
-.. code-block:: bash
-
-   oslopolicy-policy-generator \
-     --namespace keystone \
-     --format yaml \
-     --output-file keystone-policy.yaml
-
-To show the additional options and arguments supported by
-``oslopolicy-policy-generator``:
-
-.. code-block:: bash
-
-   oslopolicy-policy-generator --help
-
-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 keystone --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
-
-oslopolicy_validator
-====================
-
-The ``oslopolicy-validator`` tool can be used to perform basic sanity checks
-against a policy file. It will detect the following problems:
-
-* A missing policy file
-* Rules which have invalid syntax
-* Rules which reference non-existent other rules
-* Rules which form a cyclical reference with another rule
-* Rules which do not exist in the specified namespace
-
-This tool does very little validation of the content of the rules. Other tools,
-such as ``oslopolicy-checker``, should be used to check that rules do what is
-intended.
-
-``oslopolicy-validator`` exits with a ``0`` return code on success and ``1`` on
-failure.
-
-.. note:: At this time the policy validator can only handle single policy
-          files, not policy dirs.
-
-Examples
---------
-
-Validate the policy file used for Keystone:
-
-.. code-block:: bash
-
-   oslopolicy-validator --config-file /etc/keystone/keystone.conf --namespace keystone
-
-Sample output from a failed validation::
-
-   $ oslopolicy-validator --config-file keystone.conf --namespace keystone
-   WARNING:oslo_policy.policy:Policies ['foo', 'bar'] are part of a cyclical reference.
-   Invalid rules found
-   Failed to parse rule: (role:admin and system_scope:all) or (role:foo and oken.domain.id:%(target.user.domain_id)s))
-   Unknown rule found in policy file: foo
-   Unknown rule found in policy file: bar
+.. toctree::
+   :maxdepth: 1
+
+   oslopolicy-checker
+   oslopolicy-validator
+   oslopolicy-list-redundant
+   oslopolicy-policy-generator
+   oslopolicy-sample-generator
diff --git a/doc/source/cli/oslopolicy-checker.rst b/doc/source/cli/oslopolicy-checker.rst
new file mode 100644
index 0000000..b72354f
--- /dev/null
+++ b/doc/source/cli/oslopolicy-checker.rst
@@ -0,0 +1,94 @@
+==================
+oslopolicy-checker
+==================
+
+.. program:: oslopolicy-checker
+
+Synopsis
+--------
+
+::
+
+   oslopolicy-checker [-h] [--access ACCESS] [--config-dir DIR]
+                      [--config-file PATH]
+                      [--enforcer_config ENFORCER_CONFIG] [--is_admin]
+                      [--nois_admin] [--policy POLICY] [--rule RULE]
+                      [--target TARGET]
+
+Description
+-----------
+
+The ``oslopolicy-policy-generator`` command can be used to check policy against
+the OpenStack Identity API access information.
+
+Options
+-------
+
+.. include:: common/default-opts.rst
+
+.. option:: --access ACCESS
+
+    Path to a file containing OpenStack Identity API access info in JSON
+    format.
+
+.. option:: --enforcer_config ENFORCER_CONFIG
+
+    Configuration file for the oslopolicy-checker enforcer
+
+.. option:: --is_admin
+
+    Set ``is_admin=True`` on the credentials used for the evaluation.
+
+.. option:: --nois_admin
+
+    The inverse of ``--is_admin``
+
+.. option:: --policy POLICY
+
+    Path to a policy file.
+
+.. option:: --rule RULE
+
+    Rule to test.
+
+.. option:: --target TARGET
+
+    Path to a file containing custom target info in JSON format. This will be
+    used to evaluate the policy with.
+
+Examples
+--------
+
+Test all of Nova's policy with an admin token:
+
+.. code-block:: bash
+
+   oslopolicy-checker \
+     --policy /opt/stack/nova/etc/nova/policy.json
+     --access sample_data/auth_v3_token_admin.json
+
+Test the ``compute_extension:flavorextraspecs:index`` rule in Nova's policy
+with the admin member token and ``is_admin`` set to ``True``:
+
+.. code-block:: bash
+
+   oslopolicy-checker \
+     --policy /opt/stack/nova/etc/nova/policy.json \
+     --access sample_data/auth_v3_token_admin.json \
+     --is_admin=true --rule compute_extension:flavorextraspecs:index
+
+Test the ``compute_extension:flavorextraspecs:index`` rule in Nova's policy
+with the plain member token:
+
+.. code-block:: bash
+
+   oslopolicy-checker \
+     --policy /opt/stack/nova/etc/nova/policy.json \
+     --access sample_data/auth_v3_token_member.json \
+     --rule compute_extension:flavorextraspecs:index
+
+See Also
+--------
+
+:program:`oslopolicy-sample-generator`, :program:`oslopolicy-policy-generator`,
+:program:`oslopolicy-list-redundant`, :program:`oslopolicy-validator`
diff --git a/doc/source/cli/oslopolicy-list-redundant.rst b/doc/source/cli/oslopolicy-list-redundant.rst
new file mode 100644
index 0000000..ed56516
--- /dev/null
+++ b/doc/source/cli/oslopolicy-list-redundant.rst
@@ -0,0 +1,52 @@
+=========================
+oslopolicy-list-redundant
+=========================
+
+.. program:: oslopolicy-list-redundant
+
+Synopsis
+--------
+
+::
+
+  oslopolicy-list-redundant [-h] [--config-dir DIR] [--config-file PATH]
+                            [--namespace NAMESPACE]
+
+Description
+-----------
+
+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.
+
+Options
+-------
+
+.. include:: common/default-opts.rst
+
+.. include:: common/enforcer-opts.rst
+
+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
+
+See Also
+--------
+
+:program:`oslopolicy-sample-generator`, :program:`oslopolicy-policy-generator`,
+:program:`oslopolicy-checker`
diff --git a/doc/source/cli/oslopolicy-policy-generator.rst b/doc/source/cli/oslopolicy-policy-generator.rst
new file mode 100644
index 0000000..a64595d
--- /dev/null
+++ b/doc/source/cli/oslopolicy-policy-generator.rst
@@ -0,0 +1,67 @@
+===========================
+oslopolicy-policy-generator
+===========================
+
+.. program:: oslopolicy-policy-generator
+
+Synopsis
+--------
+
+::
+
+   oslopolicy-policy-generator [-h] [--config-dir DIR] [--config-file PATH]
+                               [--namespace NAMESPACE]
+                               [--output-file OUTPUT_FILE]
+
+Description
+-----------
+
+The ``oslopolicy-policy-generator`` command can be used to generate a policy
+file that shows the effective policy in use. This is generated by merging the
+registered defaults and policies loaded from a configuration file.
+
+Options
+-------
+
+.. include:: common/default-opts.rst
+
+.. include:: common/enforcer-opts.rst
+
+.. include:: common/generator-opts.rst
+
+Examples
+--------
+
+The generate the effective policy file for a namespace called ``keystone``:
+
+.. code-block:: bash
+
+   oslopolicy-policy-generator --namespace keystone
+
+To generate the effective policy file in JSON:
+
+.. code-block:: bash
+
+   oslopolicy-policy-generator --namespace keystone --format json
+
+To generate the effective policy file and output directly to a file:
+
+.. code-block:: bash
+
+   oslopolicy-policy-generator \
+     --namespace keystone \
+     --format yaml \
+     --output-file keystone-policy.yaml
+
+To show the additional options and arguments supported by
+``oslopolicy-policy-generator``:
+
+.. code-block:: bash
+
+   oslopolicy-policy-generator --help
+
+See Also
+--------
+
+:program:`oslopolicy-sample-generator`, :program:`oslopolicy-list-redundant`,
+:program:`oslopolicy-checker`
diff --git a/doc/source/cli/oslopolicy-sample-generator.rst b/doc/source/cli/oslopolicy-sample-generator.rst
new file mode 100644
index 0000000..c728771
--- /dev/null
+++ b/doc/source/cli/oslopolicy-sample-generator.rst
@@ -0,0 +1,68 @@
+===========================
+oslopolicy-sample-generator
+===========================
+
+.. program:: oslopolicy-sample-generator
+
+Synopsis
+--------
+
+::
+
+   oslopolicy-sample-generator [-h] [--config-dir DIR]
+                               [--config-file PATH] [--format FORMAT]
+                               [--namespace NAMESPACE]
+                               [--output-file OUTPUT_FILE]
+
+
+Description
+-----------
+
+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.
+
+Options
+-------
+
+.. include:: common/default-opts.rst
+
+.. include:: common/rule-opts.rst
+
+.. include:: common/generator-opts.rst
+
+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 keystone --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
+
+See Also
+--------
+
+:program:`oslopolicy-policy-generator`, :program:`oslopolicy-list-redundant`,
+:program:`oslopolicy-checker`
diff --git a/doc/source/cli/oslopolicy-validator.rst b/doc/source/cli/oslopolicy-validator.rst
new file mode 100644
index 0000000..11b7cb9
--- /dev/null
+++ b/doc/source/cli/oslopolicy-validator.rst
@@ -0,0 +1,58 @@
+====================
+oslopolicy-validator
+====================
+
+.. program:: oslopolicy-policy-validator
+
+Synopsis
+--------
+
+::
+
+  oslopolicy-policy-validator
+
+Description
+-----------
+
+The ``oslopolicy-validator`` tool can be used to perform basic sanity checks
+against a policy file. It will detect the following problems:
+
+* A missing policy file
+* Rules which have invalid syntax
+* Rules which reference non-existent other rules
+* Rules which form a cyclical reference with another rule
+* Rules which do not exist in the specified namespace
+
+This tool does very little validation of the content of the rules. Other tools,
+such as ``oslopolicy-checker``, should be used to check that rules do what is
+intended.
+
+Options
+-------
+
+.. include:: common/default-opts.rst
+
+.. include:: common/enforcer-opts.rst
+
+Examples
+--------
+
+Validate the policy file used for Keystone:
+
+.. code-block:: bash
+
+   oslopolicy-validator --config-file /etc/keystone/keystone.conf --namespace keystone
+
+Sample output from a failed validation::
+
+   $ oslopolicy-validator --config-file keystone.conf --namespace keystone
+   WARNING:oslo_policy.policy:Policies ['foo', 'bar'] are part of a cyclical reference.
+   Invalid rules found
+   Failed to parse rule: (role:admin and system_scope:all) or (role:foo and oken.domain.id:%(target.user.domain_id)s))
+   Unknown rule found in policy file: foo
+   Unknown rule found in policy file: bar
+
+See Also
+--------
+
+:program:`oslopolicy-checker`
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 0ec69f1..d47d4bc 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -40,7 +40,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-copyright = u'2014, OpenStack Foundation'
+copyright = '2014-2020, OpenStack Foundation'
 source_tree = 'https://opendev.org/openstack/oslo.policy/src/branch/master'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -62,6 +62,37 @@ modindex_common_prefix = ['oslo_policy.']
 # Sphinx are currently 'default' and 'sphinxdoc'.
 html_theme = 'openstackdocs'
 
+# -- Options for man page output ---------------------------------------------
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+_man_pages = [
+    (
+        'oslopolicy-checker',
+        'Check policy against the OpenStack Identity API access information.',
+    ),
+    (
+        'oslopolicy-list-redundant',
+        'Detect policies that are specified in policy files that are the same '
+        'as the defaults provided by the service',
+    ),
+    (
+        'oslopolicy-policy-generator',
+        'Generate a policy file that shows the effective policy in use',
+    ),
+    (
+        'oslopolicy-sample-generator',
+        'Generate a sample policy file based on the default policies in a '
+        'given namespace',
+    ),
+]
+
+man_pages = [
+    (f'cli/{name}', name, description, 'OpenStack Community', 1)
+    for name, description in _man_pages
+]
+
 # -- sphinx.ext.extlinks configuration ---------------------------------------
 
 extlinks = {