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>
2022-01-31 16:00:34 +05:30 · 2022-01-31 16:00:34 +05:30 · 9294a2df8f
parent ad9d3e1399
commit 9294a2df8f
14 changed files with 52 additions and 53 deletions
--- a/README.md
+++ b/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
--- a/changelogs/fragments/docfix_minor_corrections.yaml
+++ b/changelogs/fragments/docfix_minor_corrections.yaml
@ -0,0 +1,3 @@
+---
+doc_changes:
+  - "Enhancement in documentation and docstring."
--- a/docs/ansible.utils.cidr_merge_filter.rst
+++ b/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
--- a/docs/ansible.utils.keep_keys_filter.rst
+++ b/docs/ansible.utils.keep_keys_filter.rst
@ -277,8 +277,8 @@ Examples
        ansible.builtin.set_fact:
          data: "{{ interfaces }}"

-        - debug:
-            msg:  "{{ data|ansible.utils.keep_keys(target=['desc', 'name'], matching_parameter= 'starts_with') }}"
+      - debug:
+          msg:  "{{ data|ansible.utils.keep_keys(target=['desc', 'name'], matching_parameter= 'starts_with') }}"

    ##Output
    # TASK [keep selective keys from python dict/list of dict] **************************
--- a/docs/ansible.utils.update_fact_module.rst
+++ b/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:
--- a/docs/ansible.utils.validate_filter.rst
+++ b/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') }}"



--- a/docs/ansible.utils.validate_lookup.rst
+++ b/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>
--- a/plugins/action/cli_parse.py
+++ b/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
--- a/plugins/filter/validate.py
+++ b/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"""
--- a/plugins/lookup/validate.py
+++ b/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
--- a/plugins/module_utils/common/argspec_validate.py
+++ b/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
--- a/plugins/module_utils/common/index_of.py
+++ b/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
--- a/plugins/modules/update_fact.py
+++ b/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:
--- a/plugins/sub_plugins/validate/jsonschema.py
+++ b/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"))