doc fixes (#134)

Minor documentation fixes

SUMMARY

Minor documentation fixes and updated doc-string

ISSUE TYPE


Docs Pull Request

Reviewed-by: Ashwini Mhatre <mashu97@gmail.com>
Reviewed-by: None <None>

README.md

@@ -10,6 +10,8 @@ The Ansible ``ansible.utils`` collection includes a variety of plugins that aid
 
 This collection has been tested against following Ansible versions: **>=2.9.10**.
 
+For collections that support Ansible 2.9, please ensure you update your `network_os` to use the 
+fully qualified collection name (for example, `cisco.ios.ios`). 
 Plugins and modules within a collection may be tested with only specific Ansible versions.
 A collection may contain metadata that identifies these versions.
 PEP440 is the schema used to describe the versions of Ansible.
@@ -26,28 +28,25 @@ Name | Description
 [ansible.utils.get_path](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.get_path_filter.rst)|Retrieve the value in a variable using a path
 [ansible.utils.hwaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.hwaddr_filter.rst)|HWaddr / MAC address filters
 [ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_filter.rst)|Find the indices of items in a list matching some criteria
-[ansible.utils.keep_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.keep_keys_filter.rst)|Keep specific keys from a data recursively.
-[ansible.utils.nthhost](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.nthhost_filter.rst)|This filter returns the nth host within a network described by value.
-[ansible.utils.ipv4](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv4_filter.rst)|To filter only Ipv4 addresses Ipv4 filter is used.
-[ansible.utils.param_list_compare](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.param_list_compare_filter.rst)|Generate the final param list combining/comparing base and provided parameters.
-[ansible.utils.remove_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.remove_keys_filter.rst)|Remove specific keys from a data recursively.
-[ansible.utils.replace_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.replace_keys_filter.rst)|Replaces specific keys with their after value from a data recursively.
-[ansible.utils.macaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.macaddr_filter.rst)|macaddr / MAC address filters
-[ansible.utils.slaac](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.slaac_filter.rst)|This filter returns the SLAAC address within a network for a given HW/MAC address.
-[ansible.utils.ipaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipaddr_filter.rst)|This filter is designed to return the input value if a query is True, else False.
-[ansible.utils.ipwrap](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipwrap_filter.rst)|This filter is designed to Wrap IPv6 addresses in [ ] brackets.
-[ansible.utils.network_in_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_usable_filter.rst)|The network_in_usable filter returns whether an address passed as an argument is usable in a network.
-[ansible.utils.network_in_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_network_filter.rst)|This filter returns whether an address or a network passed as argument is in a network.
-[ansible.utils.next_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.next_nth_usable_filter.rst)|This filter returns the next nth usable ip within a network described by value.
-[ansible.utils.ipsubnet](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipsubnet_filter.rst)|This filter can be used to manipulate network subnets in several ways.
-[ansible.utils.ipv6](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv6_filter.rst)|To filter only Ipv6 addresses Ipv6 filter is used.
 [ansible.utils.ip4_hex](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ip4_hex_filter.rst)|This filter is designed to convert IPv4 address to Hexadecimal notation with optional delimiter.
+[ansible.utils.ipaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipaddr_filter.rst)|This filter is designed to return the input value if a query is True, else False.
 [ansible.utils.ipmath](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipmath_filter.rst)|This filter is designed to do simple IP math/arithmetic.
-[ansible.utils.nthhost](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.nthhost_filter.rst)|This filter returns the nth host within a network described by value.
+[ansible.utils.ipsubnet](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipsubnet_filter.rst)|This filter can be used to manipulate network subnets in several ways.
 [ansible.utils.ipv4](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv4_filter.rst)|To filter only Ipv4 addresses Ipv4 filter is used.
+[ansible.utils.ipv6](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipv6_filter.rst)|To filter only Ipv6 addresses Ipv6 filter is used.
+[ansible.utils.ipwrap](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.ipwrap_filter.rst)|This filter is designed to Wrap IPv6 addresses in [ ] brackets.
+[ansible.utils.keep_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.keep_keys_filter.rst)|Keep specific keys from a data recursively.
+[ansible.utils.macaddr](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.macaddr_filter.rst)|macaddr / MAC address filters
+[ansible.utils.network_in_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_network_filter.rst)|This filter returns whether an address or a network passed as argument is in a network.
+[ansible.utils.network_in_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.network_in_usable_filter.rst)|The network_in_usable filter returns whether an address passed as an argument is usable in a network.
+[ansible.utils.next_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.next_nth_usable_filter.rst)|This filter returns the next nth usable ip within a network described by value.
+[ansible.utils.nthhost](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.nthhost_filter.rst)|This filter returns the nth host within a network described by value.
 [ansible.utils.param_list_compare](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.param_list_compare_filter.rst)|Generate the final param list combining/comparing base and provided parameters.
 [ansible.utils.previous_nth_usable](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.previous_nth_usable_filter.rst)|This filter returns the previous nth usable ip within a network described by value.
 [ansible.utils.reduce_on_network](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.reduce_on_network_filter.rst)|This filter reduces a list of addresses to only the addresses that match a given network.
+[ansible.utils.remove_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.remove_keys_filter.rst)|Remove specific keys from a data recursively.
+[ansible.utils.replace_keys](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.replace_keys_filter.rst)|Replaces specific keys with their after value from a data recursively.
+[ansible.utils.slaac](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.slaac_filter.rst)|This filter returns the SLAAC address within a network for a given HW/MAC address.
 [ansible.utils.to_paths](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_paths_filter.rst)|Flatten a complex object into a dictionary of paths and values
 [ansible.utils.to_xml](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_xml_filter.rst)|Convert given JSON string to XML
 [ansible.utils.usable_range](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.usable_range_filter.rst)|Expand the usable IP addresses

changelogs/fragments/docfix_minor_corrections.yaml

@@ -0,0 +1,3 @@
+---
+doc_changes:
+  - "Enhancement in documentation and docstring."

docs/ansible.utils.cidr_merge_filter.rst

@@ -85,7 +85,7 @@ Examples
 
     #### examples
     - name: cidr_merge with merge action
-        ansible.builtin.set_fact:
+      ansible.builtin.set_fact:
           value:
             - 192.168.0.0/17
             - 192.168.128.0/17
@@ -93,7 +93,7 @@ Examples
     - debug:
         msg:  "{{ value|ansible.utils.cidr_merge }}"
 
-    # TASK [cidr_merge with merge action] ******************************************************************************************************************************
+    # TASK [cidr_merge with merge action] **********************************************************************************
     # ok: [localhost] => {
     #     "ansible_facts": {
     #         "value": [
@@ -104,7 +104,7 @@ Examples
     #     },
     #     "changed": false
     # }
-    # TASK [debug] *****************************************************************************************************************************************************
+    # TASK [debug] *********************************************************************************************************
     # ok: [loalhost] => {
     #     "msg": [
     #         "192.168.0.0/16"
@@ -112,7 +112,7 @@ Examples
     # }
 
     - name: Cidr_merge with span.
-        ansible.builtin.set_fact:
+      ansible.builtin.set_fact:
             value:
               - 192.168.1.1
               - 192.168.1.2

docs/ansible.utils.keep_keys_filter.rst

@@ -277,8 +277,8 @@ Examples
         ansible.builtin.set_fact:
           data: "{{ interfaces }}"
 
-        - debug:
+      - debug:
-            msg:  "{{ data|ansible.utils.keep_keys(target=['desc', 'name'], matching_parameter= 'starts_with') }}"
+          msg:  "{{ data|ansible.utils.keep_keys(target=['desc', 'name'], matching_parameter= 'starts_with') }}"
 
     ##Output
     # TASK [keep selective keys from python dict/list of dict] **************************

docs/ansible.utils.update_fact_module.rst

@@ -101,7 +101,7 @@ Examples
 
 .. code-block:: yaml
 
-    # Update an exisitng fact, dot or bracket notation
+    # Update an existing fact, dot or bracket notation
     - name: Set a fact
       ansible.builtin.set_fact:
         a:

docs/ansible.utils.validate_filter.rst

@@ -90,7 +90,7 @@ Parameters
                     </td>
                 <td>
                         <div>The name of the validator plugin to use.</div>
-                        <div>This option can be passed in lookup plugin as a key, value pair. For example <code>config_data|ansible.utils.validate(config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.uitls.jsonschema</code> will be used.</div>
+                        <div>This option can be passed in lookup plugin as a key, value pair. For example <code>config_data|ansible.utils.validate(config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.utils.jsonschema</code> will be used.</div>
                         <div>The value should be in fully qualified collection name format that is <code>&lt;org-name&gt;.&lt;collection-name&gt;.&lt;validator-plugin-name&gt;</code>.</div>
                 </td>
             </tr>
@@ -121,7 +121,7 @@ Examples
 
     - name: validate data in json format using jsonschema by passing plugin configuration variable as key/value pairs
       ansible.builtin.set_fact:
-        data_validilty: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
+        data_validity: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
 
 
 

docs/ansible.utils.validate_lookup.rst

@@ -90,7 +90,7 @@ Parameters
                     </td>
                 <td>
                         <div>The name of the validate plugin to use.</div>
-                        <div>This option can be passed in lookup plugin as a key, value pair. For example <code>lookup(config_data, config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.uitls.jsonschema</code> will be used.</div>
+                        <div>This option can be passed in lookup plugin as a key, value pair. For example <code>lookup(config_data, config_criteria, engine=&#x27;ansible.utils.jsonschema&#x27;</code>), in this case the value <code>ansible.utils.jsonschema</code> represents the engine to be use for data validation. If the value is not provided the default value that is <code>ansible.utils.jsonschema</code> will be used.</div>
                         <div>The value should be in fully qualified collection name format that is <code>&lt;org-name&gt;.&lt;collection-name&gt;.&lt;validate-plugin-name&gt;</code>.</div>
                 </td>
             </tr>

plugins/action/cli_parse.py

@@ -44,8 +44,7 @@ ARGSPEC_CONDITIONALS = {
 
 
 class ActionModule(ActionBase):
-    """ action module
+    """action module"""
-    """
 
     PARSER_CLS_NAME = "CliParser"
 
@@ -57,7 +56,7 @@ class ActionModule(ActionBase):
         self._task_vars = None
 
     def _debug(self, msg):
-        """ Output text using ansible's display
+        """Output text using ansible's display
 
         :param msg: The message
         :type msg: str
@@ -68,7 +67,7 @@ class ActionModule(ActionBase):
         self._display.vvvv(msg)
 
     def _fail_json(self, msg):
-        """ Replace the AnsibleModule fai_json here
+        """Replace the AnsibleModule fai_json here
 
         :param msg: The message for the failure
         :type msg: str
@@ -77,7 +76,7 @@ class ActionModule(ActionBase):
         raise AnsibleActionFail(msg)
 
     def _extended_check_argspec(self):
-        """ Check additional requirements for the argspec
+        """Check additional requirements for the argspec
         that cannot be covered using stnd techniques
         """
         errors = []
@@ -101,7 +100,7 @@ class ActionModule(ActionBase):
             self._result["msg"] = " ".join(errors)
 
     def _load_parser(self, task_vars):
-        """ Load a parser from the fs
+        """Load a parser from the fs
 
         :param task_vars: The vars provided when the task was run
         :type task_vars: dict
@@ -140,7 +139,7 @@ class ActionModule(ActionBase):
             )
             return parser
         except Exception as exc:
-            # TODO: The condition is added to support old sub-plugin strucutre.
+            # TODO: The condition is added to support old sub-plugin structure.
             # Remove the if condition after ansible.netcommon.cli_parse module is removed
             # from ansible.netcommon collection
             if cref["cname"] == "netcommon" and cref["plugin"] in [
@@ -175,8 +174,7 @@ class ActionModule(ActionBase):
             return None
 
     def _set_parser_command(self):
-        """ Set the /parser/command in the task args based on /command if needed
+        """Set the /parser/command in the task args based on /command if needed"""
-        """
         if self._task.args.get("command"):
             if not self._task.args.get("parser").get("command"):
                 self._task.args.get("parser")["command"] = self._task.args.get(
@@ -184,13 +182,12 @@ class ActionModule(ActionBase):
                 )
 
     def _set_text(self):
-        """ Set the /text in the task_args based on the command run
+        """Set the /text in the task_args based on the command run"""
-        """
         if self._result.get("stdout"):
             self._task.args["text"] = self._result["stdout"]
 
     def _os_from_task_vars(self):
-        """ Extract an os str from the task's vars
+        """Extract an os str from the task's vars
 
         :return: A short OS name
         :rtype: str
@@ -216,7 +213,7 @@ class ActionModule(ActionBase):
         return oper_sys.lower()
 
     def _update_template_path(self, template_extension):
-        """ Update the template_path in the task args
+        """Update the template_path in the task args
         If not provided, generate template name using os and command
 
         :param template_extension: The parser specific template extension
@@ -242,7 +239,7 @@ class ActionModule(ActionBase):
             self._task.args["parser"]["template_path"] = source
 
     def _get_template_contents(self):
-        """ Retrieve the contents of the parser template
+        """Retrieve the contents of the parser template
 
         :return: The parser's contents
         :rtype: str
@@ -269,7 +266,7 @@ class ActionModule(ActionBase):
         return template_contents
 
     def _prune_result(self):
-        """ In the case of an error, remove stdout and stdout_lines
+        """In the case of an error, remove stdout and stdout_lines
         this allows for easier visibility of the error message.
         In the case of an actual command error, it will be thrown
         in the module
@@ -278,7 +275,7 @@ class ActionModule(ActionBase):
         self._result.pop("stdout_lines", None)
 
     def _run_command(self):
-        """ Run a command on the host
+        """Run a command on the host
         If socket_path exists, assume it's a network device
         else, run a low level command
         """
@@ -303,7 +300,7 @@ class ActionModule(ActionBase):
                 self._result["stdout_lines"] = result["stdout_lines"]
 
     def run(self, tmp=None, task_vars=None):
-        """ The std execution entry pt for an action plugin
+        """The std execution entry pt for an action plugin
 
         :param tmp: no longer used
         :type tmp: none

plugins/filter/validate.py

@@ -35,7 +35,7 @@ DOCUMENTATION = """
         - This option can be passed in lookup plugin as a key, value pair.
           For example C(config_data|ansible.utils.validate(config_criteria, engine='ansible.utils.jsonschema')), in
           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.uitls.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
           C(<org-name>.<collection-name>.<validator-plugin-name>).
         default: ansible.utils.jsonschema
@@ -58,7 +58,7 @@ EXAMPLES = r"""
 
 - name: validate data in json format using jsonschema by passing plugin configuration variable as key/value pairs
   ansible.builtin.set_fact:
-    data_validilty: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
+    data_validity: "{{ data|ansible.utils.validate(criteria, engine='ansible.utils.jsonschema', draft='draft7') }}"
 """
 
 RETURN = """
@@ -138,7 +138,7 @@ def validate(*args, **kwargs):
 
 
 class FilterModule(object):
-    """ index_of  """
+    """index_of"""
 
     def filters(self):
         """a mapping of filter names to functions"""

plugins/lookup/validate.py

@@ -42,7 +42,7 @@ DOCUMENTATION = """
         - 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
           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.uitls.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
           C(<org-name>.<collection-name>.<validate-plugin-name>).
         default: ansible.utils.jsonschema

plugins/module_utils/common/argspec_validate.py

@@ -141,7 +141,7 @@ class AnsibleArgSpecValidator:
         other_args=None,
     ):
         """Validate some data against a schema
-        :param data: The data to valdiate
+        :param data: The data to validate
         :type data: dict
         :param schema: A schema in ansible argspec format
         :type schema: dict

plugins/module_utils/common/index_of.py

@@ -66,7 +66,7 @@ def _run_test(entry, test, right, tests):
     :type test: a lambda from the qual_map
     :param entry: The x for the lambda
     :type entry: str int or bool
-    :param right: The y for the lamba
+    :param right: The y for the lambda
     :type right: str int bool or list
     :return: If the test passed
     :rtype: book
@@ -134,7 +134,7 @@ def index_of(
     :param data: The data passed in (data|index_of(...))
     :type data: unknown
     :param test: the test to use
-    :type test: jinj2 test
+    :type test: jinja2 test
     :param value: The value to use for the test
     :type value: unknown
     :param key: The key to use when a list of dicts is passed

plugins/modules/update_fact.py

@@ -49,7 +49,7 @@ author:
 
 EXAMPLES = r"""
 
-# Update an exisitng fact, dot or bracket notation
+# Update an existing fact, dot or bracket notation
 - name: Set a fact
   ansible.builtin.set_fact:
     a:

plugins/sub_plugins/validate/jsonschema.py

@@ -53,7 +53,7 @@ from ansible_collections.ansible.utils.plugins.module_utils.common.utils import
     to_list,
 )
 
-# PY2 compatiblilty for JSONDecodeError
+# PY2 compatibility for JSONDecodeError
 try:
     from json.decoder import JSONDecodeError
 except ImportError:
@@ -86,7 +86,7 @@ class Validate(ValidateBase):
     def _check_reqs():
         """Check the prerequisites are installed for jsonschema
 
-        :return None: In case all prerequisites are satisfised
+        :return None: In case all prerequisites are satisfied
         """
         if not HAS_JSONSCHEMA:
             raise AnsibleError(missing_required_lib("jsonschema"))