Github action for unit and sanity tests (#172)

.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Test collection
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sanity:
+    uses: ansible-network/github_actions/.github/workflows/sanity.yml@main
+  unit-galaxy:
+    uses: ansible-network/github_actions/.github/workflows/unit_simple.yml@main
+
+  all_green:
+    if: ${{ always() }}
+    needs:
+      - sanity
+      - unit-galaxy
+    runs-on: ubuntu-latest
+    steps:
+      - run: >-
+          python -c "assert set([
+          '${{ needs.sanity.result }}',
+          '${{ needs.unit-galaxy.result }}'
+          ]) == {'success'}"

changelogs/fragments/172.yaml

@@ -0,0 +1,4 @@
+---
+trivial:
+  - Enable GH action for unit ans sanity tests
+  - Several minor doc string updates to get sanity to pass with devel/milestone

plugins/lookup/get_path.py

@@ -18,25 +18,26 @@ DOCUMENTATION = """
     version_added: "1.0.0"
     short_description: Retrieve the value in a variable using a path
     description:
-        - Use a I(path) to retrieve a nested value from a I(var)
+      - Use a I(path) to retrieve a nested value from a I(var)
-        - B(get_path) is also available as a B(filter plugin) for convenience
+      - B(get_path) is also available as a B(filter plugin) for convenience
-        - Using the parameters below- C(lookup('ansible.utils.get_path', var, path, wantlist))
+      - Using the parameters below- C(lookup('ansible.utils.get_path', var, path, wantlist))
     options:
       var:
-        description: The variable from which the value should be extracted.
+        description:
+          - The variable from which the value should be extracted.
         type: raw
         required: True
       path:
-        description: >
+        description:
-            The I(path) in the I(var) to retrieve the value of.
+          - The I(path) in the I(var) to retrieve the value of.
-            The I(path) needs to a be a valid jinja path.
+          - The I(path) needs to a be a valid jinja path.
         type: str
         required: True
       wantlist:
-        description: >
+        description:
-            If set to C(True), the return value will always be a list.
+          - If set to C(True), the return value will always be a list.
-            This can also be accomplished using C(query) or C(q) instead of C(lookup).
+          - This can also be accomplished using C(query) or C(q) instead of C(lookup).
-            U(https://docs.ansible.com/ansible/latest/plugins/lookup.html).
+          - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html).
         type: bool
 
     notes:
@@ -170,8 +171,10 @@ class LookupModule(LookupBase):
             keys = ["var", "path"]
             terms = dict(zip(keys, terms))
         terms.update(kwargs)
+
+        schema = [v for k, v in globals() if k.lower() == "documentation"]
         aav = AnsibleArgSpecValidator(
-            data=terms, schema=DOCUMENTATION, name="get_path"
+            data=terms, schema=schema[0], name="get_path"
         )
         valid, errors, updated_data = aav.validate()
         if not valid:

plugins/lookup/index_of.py

@@ -17,45 +17,47 @@ DOCUMENTATION = """
     author: Bradley Thornton (@cidrblock)
     version_added: "1.0.0"
     short_description: Find the indices of items in a list matching some criteria
-    description:
+    description: foo
-        - This plugin returns the indices of items matching some criteria in a list.
+      - This plugin returns the indices of items matching some criteria in a list.
-        - When working with a list of dictionaries, the key to evaluate can be specified.
+      - When working with a list of dictionaries, the key to evaluate can be specified.
-        - B(index_of) is also available as a B(filter plugin) for convenience.
+      - B(index_of) is also available as a B(filter plugin) for convenience.
-        - Using the parameters below- C(lookup('ansible.utils.index_of', data, test, value, key, fail_on_missing, wantlist)).
+      - 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.
+        description:
+          - A list of items to enumerate and test against.
         type: list
         elements: raw
         required: True
       test:
-        description: >
+        description:
-            The name of the test to run against the list, a valid jinja2 test or ansible test plugin.
+          - The name of the test to run against the list, a valid jinja2 test or ansible test plugin.
-            Jinja2 includes the following tests U(http://jinja.palletsprojects.com/templates/#builtin-tests).
+          - Jinja2 includes the following tests U(http://jinja.palletsprojects.com/templates/#builtin-tests).
-            An overview of tests included in ansible U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html).
+          - An overview of tests included in ansible U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_tests.html).
         type: str
         required: True
       value:
-        description: >
+        description:
-            The value used to test each list item against.
+          - The value used to test each list item against.
-            Not required for simple tests (eg: C(true), C(false), C(even), C(odd))
+          - Not required for simple tests (e.g. C(true), C(false), C(even), C(odd))
-            May be a C(string), C(boolean), C(number), C(regular expression) C(dict) and so on, depending on the B(test) used.
+          - May be a C(string), C(boolean), C(number), C(regular expression) C(dict) and so on, depending on the B(test) used.
         type: raw
       key:
-        description: >
+        description:
-            When the data provided is a list of dictionaries, run the test against this dictionary key.
+          - When the data provided is a list of dictionaries, run the test against this dictionary key.
-            When using a I(key), the I(data) must only contain dictionaries.
+          - When using a I(key), the I(data) must only contain dictionaries.
-            See I(fail_on_missing) below to determine the behaviour when the I(key) is missing from a dictionary in the I(data).
+          - See I(fail_on_missing) below to determine the behaviour when the I(key) is missing from a dictionary in the I(data).
         type: str
       fail_on_missing:
-        description: When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
+        description:
+        - When provided a list of dictionaries, fail if the key is missing from one or more of the dictionaries.
         type: bool
       wantlist:
-        description: >
+        description:
-            When only a single entry in the I(data) is matched, the index of that entry is returned as an integer.
+          - When only a single entry in the I(data) is matched, the index of that entry is returned as an integer.
-            If set to C(True), the return value will always be a list, even if only a single entry is matched.
+          - If set to C(True), the return value will always be a list, even if only a single entry is matched.
-            This can also be accomplished using C(query) or C(q) instead of C(lookup).
+          - This can also be accomplished using C(query) or C(q) instead of C(lookup).
-            U(https://docs.ansible.com/ansible/latest/plugins/lookup.html)
+          - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html)
         type: bool
 
     notes:
@@ -338,8 +340,10 @@ class LookupModule(LookupBase):
             ]
             terms = dict(zip(keys, terms))
         terms.update(kwargs)
+
+        schema = [v for k, v in globals() if k.lower() == "documentation"]
         aav = AnsibleArgSpecValidator(
-            data=terms, schema=DOCUMENTATION, name="index_of"
+            data=terms, schema=schema[0], name="index_of"
         )
         valid, errors, updated_data = aav.validate()
         if not valid:

plugins/lookup/to_paths.py

@@ -18,25 +18,27 @@ DOCUMENTATION = """
     version_added: "1.0.0"
     short_description: Flatten a complex object into a dictionary of paths and values
     description:
-        - Flatten a complex object into a dictionary of paths and values.
+      - Flatten a complex object into a dictionary of paths and values.
-        - Paths are dot delimited whenever possible.
+      - Paths are dot delimited whenever possible.
-        - Brackets are used for list indices and keys that contain special characters.
+      - Brackets are used for list indices and keys that contain special characters.
-        - B(to_paths) is also available as a filter plugin.
+      - B(to_paths) is also available as a filter plugin.
-        - Using the parameters below- C(lookup('ansible.utils.to_paths', var, prepend, wantlist))
+      - Using the parameters below- C(lookup('ansible.utils.to_paths', var, prepend, wantlist))
     options:
       var:
-        description: The value of I(var) will be used.
+        description:
+          - The value of I(var) will be used.
         type: raw
         required: True
       prepend:
-        description: Prepend each path entry. Useful to add the initial I(var) name.
+        description:
+          - Prepend each path entry. Useful to add the initial I(var) name.
         type: str
         required: False
       wantlist:
-        description: >
+        description:
-            If set to I(True), the return value will always be a list.
+          - If set to I(True), the return value will always be a list.
-            This can also be accomplished using C(query) or B(q) instead of C(lookup).
+          - This can also be accomplished using C(query) or B(q) instead of C(lookup).
-            U(https://docs.ansible.com/ansible/latest/plugins/lookup.html)
+          - U(https://docs.ansible.com/ansible/latest/plugins/lookup.html)
         type: bool
 
     notes:
@@ -141,8 +143,10 @@ class LookupModule(LookupBase):
             keys = ["var", "prepend"]
             terms = dict(zip(keys, terms))
         terms.update(kwargs)
+
+        schema = [v for k, v in globals() if k.lower() == "documentation"]
         aav = AnsibleArgSpecValidator(
-            data=terms, schema=DOCUMENTATION, name="to_paths"
+            data=terms, schema=schema[0], name="to_paths"
         )
         valid, errors, updated_data = aav.validate()
         if not valid:

plugins/lookup/validate.py

@@ -13,47 +13,47 @@ DOCUMENTATION = """
     version_added: "1.0.0"
     short_description: Validate data with provided criteria
     description:
-        - Validate I(data) with provided I(criteria) based on the validation I(engine).
+      - Validate I(data) with provided I(criteria) based on the validation I(engine).
     options:
       data:
         type: raw
         description:
-        - Data that will be validated against I(criteria).
+          - Data that will be validated against I(criteria).
-        - This option represents the value that is passed to the lookup plugin as the first argument.
+          - This option represents the value that is passed to the lookup plugin as the first argument.
-          For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')),
+            For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')),
-          in this case C(config_data) represents this option.
+            in this case C(config_data) represents this option.
-        - For the type of I(data) that represents this value refer to the documentation of individual validate plugins.
+          - For the type of I(data) that represents this value refer to the documentation of individual validate plugins.
         required: True
       criteria:
         type: raw
         description:
-        - The criteria used for validation of value that represents I(data) options.
+          - The criteria used for validation of value that represents I(data) options.
-        - This option represents the second argument passed in the lookup plugin
+          - This option represents the second argument passed in the lookup plugin
-          For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')),
+            For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')),
-          in this case the value of C(config_criteria) represents this option.
+            in this case the value of C(config_criteria) represents this option.
-        - For the type of I(criteria) that represents this value refer to the documentation of individual
+          - For the type of I(criteria) that represents this value refer to the documentation of individual
-          validate plugins.
+            validate plugins.
         required: True
       engine:
         type: str
         description:
-        - The name of the validate plugin to use.
+          - The name of the validate plugin to use.
-        - This option can be passed in lookup plugin as a key, value pair.
+          - This option can be passed in lookup plugin as a key, value pair.
-          For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), in
+            For example C(lookup(config_data, config_criteria, engine='ansible.utils.jsonschema')), in
-          this case the value C(ansible.utils.jsonschema) represents the engine to be use for data validation.
+            this case the value C(ansible.utils.jsonschema) represents the engine to be use for data validation.
-          If the value is not provided the default value that is C(ansible.utils.jsonschema) will be used.
+            If the value is not provided the default value that is C(ansible.utils.jsonschema) will be used.
-        - The value should be in fully qualified collection name format that is
+          - The value should be in fully qualified collection name format that is
-          C(<org-name>.<collection-name>.<validate-plugin-name>).
+            C(<org-name>.<collection-name>.<validate-plugin-name>).
         default: ansible.utils.jsonschema
     notes:
-    - For the type of options I(data) and I(criteria) refer to the individual validate plugin
+      - For the type of options I(data) and I(criteria) refer to the individual validate plugin
-      documentation that is represented in the value of I(engine) option.
+        documentation that is represented in the value of I(engine) option.
-    - For additional plugin configuration options refer to the individual validate plugin
+      - For additional plugin configuration options refer to the individual validate plugin
-      documentation that is represented by the value of I(engine) option.
+        documentation that is represented by the value of I(engine) option.
-    - The plugin configuration option can be either passed as C(key=value) pairs within lookup plugin
+      - The plugin configuration option can be either passed as C(key=value) pairs within lookup plugin
-      or task or environment variables.
+        or task or environment variables.
-    - The precedence the validate plugin configurable option is the variable passed within lookup plugin
+      - The precedence the validate plugin configurable option is the variable passed within lookup plugin
-      as C(key=value) pairs followed by task variables followed by environment variables.
+        as C(key=value) pairs followed by task variables followed by environment variables.
 """
 
 EXAMPLES = r"""
@@ -109,9 +109,12 @@ class LookupModule(LookupBase):
         if kwargs.get("engine"):
             params.update({"engine": kwargs["engine"]})
 
+        schema = [
+            v for k, v in globals().items() if k.lower() == "documentation"
+        ]
         valid, argspec_result, updated_params = check_argspec(
-            DOCUMENTATION,
+            schema=schema[0],
-            "validate lookup",
+            name="validate lookup",
             schema_conditionals=ARGSPEC_CONDITIONALS,
             **params
         )