From a727928e3d209b852d25c2729f3634e00b22b72b Mon Sep 17 00:00:00 2001
From: "Bradley A. Thornton" <bthornto@redhat.com>
Date: Wed, 21 Oct 2020 11:22:30 -0700
Subject: [PATCH] Show params in use for lookup and filter plugins (#18)

* Dedicated DOCUMENTATION for get_path

* Comment out cross collection example

* Remove sanity exception, unneeded

* Remove extra empty lines

* Dedicated DOCUMENTATION for index_of filter plugin

* Dedicated DOCUMENTATION for to_paths filter plugin

* Add rst docs for filter plugins, update README

* lint and pep8 fixes

* filter plugin doc update for wantlist

* Because doc keys are sorted, add example of options in use

* Update docs

Co-authored-by: cidrblock <brad@thethorntons.net>
---
 docs/ansible.utils.get_path_filter.rst | 1 +
 docs/ansible.utils.get_path_lookup.rst | 1 +
 docs/ansible.utils.index_of_filter.rst | 1 +
 docs/ansible.utils.index_of_lookup.rst | 1 +
 docs/ansible.utils.to_paths_filter.rst | 1 +
 docs/ansible.utils.to_paths_lookup.rst | 1 +
 plugins/filter/get_path.py             | 1 +
 plugins/filter/index_of.py             | 1 +
 plugins/filter/to_paths.py             | 1 +
 plugins/lookup/get_path.py             | 1 +
 plugins/lookup/index_of.py             | 1 +
 plugins/lookup/to_paths.py             | 1 +
 12 files changed, 12 insertions(+)

diff --git a/docs/ansible.utils.get_path_filter.rst b/docs/ansible.utils.get_path_filter.rst
index 02d5066..b7ae2f5 100644
--- a/docs/ansible.utils.get_path_filter.rst
+++ b/docs/ansible.utils.get_path_filter.rst
@@ -19,6 +19,7 @@ Synopsis
 --------
 - Use a ``path`` to retreive a nested value from a ``var``
 - ``get_path`` is also available as a ``lookup plugin`` for convenience
+- Using the parameters below- ``var|ansible.utils.get_path(path, wantlist``)
 
 
 
diff --git a/docs/ansible.utils.get_path_lookup.rst b/docs/ansible.utils.get_path_lookup.rst
index dee4f6b..11aa0d6 100644
--- a/docs/ansible.utils.get_path_lookup.rst
+++ b/docs/ansible.utils.get_path_lookup.rst
@@ -19,6 +19,7 @@ Synopsis
 --------
 - Use a ``path`` to retreive a nested value from a ``var``
 - ``get_path`` is also available as a ``filter plugin`` for convenience
+- Using the parameters below- ``lookup('ansible.utils.get_path', var, path, wantlist``)
 
 
 
diff --git a/docs/ansible.utils.index_of_filter.rst b/docs/ansible.utils.index_of_filter.rst
index c0db31d..d9900d7 100644
--- a/docs/ansible.utils.index_of_filter.rst
+++ b/docs/ansible.utils.index_of_filter.rst
@@ -20,6 +20,7 @@ Synopsis
 - This plugin returns the indicies of items matching some criteria in a list
 - When working with a list of dictionaries, the key to evaluate can be specified
 - ``index_of`` is also available as a ``lookup plugin`` for convenience
+- Using the parameters below- ``data|ansible.utils.index_of(test, value, key, fail_on_missing, wantlist``)
 
 
 
diff --git a/docs/ansible.utils.index_of_lookup.rst b/docs/ansible.utils.index_of_lookup.rst
index d425b39..b9c9e55 100644
--- a/docs/ansible.utils.index_of_lookup.rst
+++ b/docs/ansible.utils.index_of_lookup.rst
@@ -20,6 +20,7 @@ Synopsis
 - This plugin returns the indicies of items matching some criteria in a list
 - When working with a list of dictionaries, the key to evaluate can be specified
 - ``index_of`` is also available as a ``filter plugin`` for convenience
+- Using the parameters below- ``lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist``)
 
 
 
diff --git a/docs/ansible.utils.to_paths_filter.rst b/docs/ansible.utils.to_paths_filter.rst
index 064292d..e071222 100644
--- a/docs/ansible.utils.to_paths_filter.rst
+++ b/docs/ansible.utils.to_paths_filter.rst
@@ -21,6 +21,7 @@ Synopsis
 - Paths are dot delimited whenever possible
 - Brakets are used for list indicies and keys that contain special characters
 - ``to_paths`` is also available as a ``lookup plugin`` for convenience
+- Using the parameters below- ``var|ansible.utils.to_paths(prepend, wantlist``)
 
 
 
diff --git a/docs/ansible.utils.to_paths_lookup.rst b/docs/ansible.utils.to_paths_lookup.rst
index 5021e7d..941ee63 100644
--- a/docs/ansible.utils.to_paths_lookup.rst
+++ b/docs/ansible.utils.to_paths_lookup.rst
@@ -21,6 +21,7 @@ Synopsis
 - Paths are dot delimited whenever possible
 - Brakets are used for list indicies and keys that contain special characters
 - ``to_paths`` is also available as a filter plugin
+- Using the parameters below- ``lookup('ansible.utils.to_paths', var, prepend, wantlist``)
 
 
 
diff --git a/plugins/filter/get_path.py b/plugins/filter/get_path.py
index e01962c..6eb8e70 100644
--- a/plugins/filter/get_path.py
+++ b/plugins/filter/get_path.py
@@ -19,6 +19,7 @@ DOCUMENTATION = """
     description:
         - Use a C(path) to retreive a nested value from a C(var)
         - C(get_path) is also available as a C(lookup plugin) for convenience
+        - Using the parameters below- C(var|ansible.utils.get_path(path, wantlist))
     options:
       var:
         description:
diff --git a/plugins/filter/index_of.py b/plugins/filter/index_of.py
index a3d7d55..0a7aeee 100644
--- a/plugins/filter/index_of.py
+++ b/plugins/filter/index_of.py
@@ -20,6 +20,7 @@ DOCUMENTATION = """
         - This plugin returns the indicies of items matching some criteria in a list
         - When working with a list of dictionaries, the key to evaluate can be specified
         - C(index_of) is also available as a C(lookup plugin) for convenience
+        - Using the parameters below- C(data|ansible.utils.index_of(test, value, key, fail_on_missing, wantlist))
     options:
       data:
         description:
diff --git a/plugins/filter/to_paths.py b/plugins/filter/to_paths.py
index deb0fb4..a266b05 100644
--- a/plugins/filter/to_paths.py
+++ b/plugins/filter/to_paths.py
@@ -22,6 +22,7 @@ DOCUMENTATION = """
         - Paths are dot delimited whenever possible
         - Brakets are used for list indicies and keys that contain special characters
         - C(to_paths) is also available as a C(lookup plugin) for convenience
+        - Using the parameters below- C(var|ansible.utils.to_paths(prepend, wantlist))
     options:
       var:
         description:
diff --git a/plugins/lookup/get_path.py b/plugins/lookup/get_path.py
index c281a0c..caa576f 100644
--- a/plugins/lookup/get_path.py
+++ b/plugins/lookup/get_path.py
@@ -20,6 +20,7 @@ DOCUMENTATION = """
     description:
         - Use a C(path) to retreive a nested value from a C(var)
         - C(get_path) is also available as a C(filter plugin) for convenience
+        - Using the parameters below- C(lookup('ansible.utils.get_path', var, path, wantlist))
     options:
       var:
         description: The variable from which the value should be extraced
diff --git a/plugins/lookup/index_of.py b/plugins/lookup/index_of.py
index 00889cf..0441239 100644
--- a/plugins/lookup/index_of.py
+++ b/plugins/lookup/index_of.py
@@ -21,6 +21,7 @@ DOCUMENTATION = """
         - This plugin returns the indicies of items matching some criteria in a list
         - When working with a list of dictionaries, the key to evaluate can be specified
         - C(index_of) is also available as a C(filter plugin) for convenience
+        - Using the parameters below- C(lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist))
     options:
       data:
         description: A list of items to enumerate and test against
diff --git a/plugins/lookup/to_paths.py b/plugins/lookup/to_paths.py
index 4c8e1c1..3e62712 100644
--- a/plugins/lookup/to_paths.py
+++ b/plugins/lookup/to_paths.py
@@ -22,6 +22,7 @@ DOCUMENTATION = """
         - Paths are dot delimited whenever possible
         - Brakets are used for list indicies and keys that contain special characters
         - C(to_paths) is also available as a filter plugin
+        - Using the parameters below- C(lookup('ansible.utils.to_paths', var, prepend, wantlist))
     options:
       var:
         description: The value of C(var) will be will be used.