T6910: fix documentation and argspecs are out of alignment (#358)

chore: update firewall_rules from module
fix: update firewall_global from resource model
chore: update to sync with resource module
chore: update README
fix: comment and formatting
fix: formatting issues
fix: missing imports
fix: import and metadata violations
fix: interface fixes
fix: move the arg spec comment
fix: update interface docs
fix: remove comments for non-RM versions
* T6910: fix documentation and argspecs
* T6910: docs: update per review
* T6910: docs: fix missing pipe

1 files changed, 110 insertions, 55 deletions

diff --git a/plugins/modules/vyos_bgp_global.py b/plugins/modules/vyos_bgp_global.py
index f9c0eeb3..7d47e4ad 100644
--- a/plugins/modules/vyos_bgp_global.py
+++ b/plugins/modules/vyos_bgp_global.py
@@ -1,27 +1,9 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-# Copyright 2021 Red Hat
+# Copyright 2024 Red Hat
 # GNU General Public License v3.0+
 # (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-#############################################
-#                WARNING                    #
-#############################################
-#
-# This file is auto generated by the resource
-#   module builder playbook.
-#
-# Do not edit this file manually.
-#
-# Changes to this file will be over written
-#   by the resource module builder.
-#
-# Changes should be made in the model used to
-#   generate this file or in the resource module
-#   builder template.
-#
-#############################################
-
 """
 The module file for vyos_bgp_global
 """
@@ -33,11 +15,12 @@ __metaclass__ = type
 
 DOCUMENTATION = """
 module: vyos_bgp_global
-version_added: 2.0.0
-short_description: BGP Global Resource Module.
+version_added: 1.0.0
+short_description: BGP global resource module
 description:
 - This module manages BGP global configuration of interfaces on devices running VYOS.
-author: Gomathi Selvi Srinivasan (@GomathiselviS)
+author:
+- Gomathi Selvi Srinivasan (@GomathiselviS)
 options:
   config:
     description: A dict of BGP global configuration for interfaces.
@@ -45,22 +28,25 @@ options:
     suboptions:
       as_number:
         description:
-            - AS number.
+        - AS number.
         type: int
       aggregate_address:
         description:
-          - BGP aggregate network.
+        - BGP aggregate network.
         type: list
         elements: dict
         suboptions:
           prefix:
-            description: BGP aggregate network.
+            description:
+            - BGP aggregate network.
             type: str
           as_set:
-            description: Generate AS-set path information for this aggregate address.
+            description:
+            - Generate AS-set path information for this aggregate address.
             type: bool
           summary_only:
-            description: Announce the aggregate summary network only.
+            description:
+            - Announce the aggregate summary network only.
             type: bool
       maximum_paths:
         description: BGP multipaths
@@ -79,19 +65,24 @@ options:
         elements: dict
         suboptions:
           address:
-            description: BGP neighbor address (v4/v6).
+            description:
+            - BGP neighbor address (v4/v6).
             type: str
           advertisement_interval:
-            description: Minimum interval for sending routing updates.
+            description:
+            - Minimum interval for sending routing updates.
             type: int
           allowas_in:
-            description: Number of occurrences of AS number.
+            description:
+            - Number of occurrences of AS number.
             type: int
           as_override:
-            description:  AS for routes sent to this neighbor to be the local AS.
+            description:
+            - AS for routes sent to this neighbor to be the local AS.
             type: bool
           attribute_unchanged:
-            description: BGP attributes are sent unchanged.
+            description:
+            - BGP attributes are sent unchanged.
             type: dict
             suboptions:
               as_path:
@@ -104,47 +95,58 @@ options:
                 description: next_hop
                 type: bool
           capability:
-            description: Advertise capabilities to this neighbor.
+            description:
+            - Advertise capabilities to this neighbor.
             type: dict
             suboptions:
               dynamic:
-                description: Advertise dynamic capability to this neighbor.
+                description:
+                - Advertise dynamic capability to this neighbor.
                 type: bool
               orf:
-                description: Advertise ORF capability to this neighbor.
+                description:
+                 - Advertise ORF capability to this neighbor.
                 type: str
-                choices: ['send', 'receive']
+                choices:
+                - send
+                - receive
           default_originate:
-            description: Send default route to this neighbor
+            description:
+            - Send default route to this neighbor
             type: str
           description:
-            description: description text
+            description:
+            - Description of the neighbor
             type: str
           disable_capability_negotiation:
-            description: Disbale capability negotiation with the neighbor
+            description:
+            - Disbale capability negotiation with the neighbor
             type: bool
           disable_connected_check:
-            description: Disable check to see if EBGP peer's address is a connected route.
+            description:
+            - Disable check to see if EBGP peer's address is a connected route.
             type: bool
           disable_send_community:
-            description: Disable sending community attributes to this neighbor.
+            description:
+            - Disable sending community attributes to this neighbor.
             type: str
             choices: ['extended', 'standard']
           distribute_list:
-            description:  Access-list to filter route updates to/from this neighbor.
+            description: Access-list to filter route updates to/from this neighbor.
             type: list
             elements: dict
             suboptions:
               action:
-                description:  Access-list to filter outgoing/incoming route updates to this neighbor
+                description: Access-list to filter outgoing/incoming route updates to this neighbor
                 type: str
                 choices: ['export', 'import']
               acl:
                 description: Access-list number.
                 type: int
           ebgp_multihop:
-            description: Allow this EBGP neighbor to not be on a directly connected network. Specify
-                         the number hops.
+            description:
+              - Allow this EBGP neighbor to not be on a directly connected network. Specify
+                the number hops.
             type: int
           filter_list:
             description: As-path-list to filter route updates to/from this neighbor.
@@ -162,11 +164,11 @@ options:
             description: local as number not to be prepended to updates from EBGP peers
             type: int
           maximum_prefix:
-            description:  Maximum number of prefixes to accept from this neighbor
+            description: Maximum number of prefixes to accept from this neighbor
                nexthop-self Nexthop for routes sent to this neighbor to be the local router.
             type: int
           nexthop_self:
-            description:  Nexthop for routes sent to this neighbor to be the local router.
+            description: Nexthop for routes sent to this neighbor to be the local router.
             type: bool
           override_capability:
             description: Ignore capability negotiation with specified neighbor.
@@ -178,7 +180,7 @@ options:
             description: BGP MD5 password
             type: str
           peer_group_name:
-            description:  IPv4 peer group for this peer
+            description: IPv4 peer group for this peer
             type: str
           peer_group:
             description: True if all the configs under this neighbor key is for peer group template.
@@ -232,10 +234,10 @@ options:
             description: Enable strict capability negotiation
             type: bool
           unsuppress_map:
-            description:  Route-map to selectively unsuppress suppressed routes
+            description: Route-map to selectively unsuppress suppressed routes
             type: str
           update_source:
-            description:  Source IP of routing updates
+            description: Source IP of routing updates
             type: str
           weight:
             description: Default weight for routes from this neighbor
@@ -361,7 +363,7 @@ options:
             description: Compare MEDs between different peers in the same AS
             type: bool
           disable_network_import_check:
-            description:  Disable IGP route check for network statements
+            description: Disable IGP route check for network statements
             type: bool
           distance:
             description: Administrative distances for BGP routes
@@ -424,8 +426,8 @@ options:
         transforms it into Ansible structured data as per the resource module's argspec
         and the value is then returned in the I(parsed) key within the result.
     type: str
-
 """
+
 EXAMPLES = """
 # Using merged
 # Before state
@@ -1405,6 +1407,53 @@ EXAMPLES = """
 #     ]
 """
 
+RETURN = """
+before:
+  description: The configuration prior to the module execution.
+  returned: when I(state) is C(merged), C(replaced), C(overridden), C(deleted) or C(purged)
+  type: dict
+  sample: >
+    This output will always be in the same format as the
+    module argspec.
+after:
+  description: The resulting configuration after module execution.
+  returned: when changed
+  type: dict
+  sample: >
+    This output will always be in the same format as the
+    module argspec.
+commands:
+  description: The set of commands pushed to the remote device.
+  returned: when I(state) is C(merged), C(replaced), C(overridden), C(deleted) or C(purged)
+  type: list
+  sample:
+    - set protocols bgp 65536 redistribute static route-map map01
+    - set protocols bgp 65536 network 203.0.113.0/24 route-map map01
+    - set protocols bgp 65536 parameters always-compare-med
+rendered:
+  description: The provided configuration in the task rendered in device-native format (offline).
+  returned: when I(state) is C(rendered)
+  type: list
+  sample:
+    - set protocols bgp 65536 redistribute static route-map map01
+    - set protocols bgp 65536 network 203.0.113.0/24 route-map map01
+    - set protocols bgp 65536 parameters always-compare-med
+gathered:
+  description: Facts about the network resource gathered from the remote device as structured data.
+  returned: when I(state) is C(gathered)
+  type: list
+  sample: >
+    This output will always be in the same format as the
+    module argspec.
+parsed:
+  description: The device native config provided in I(running_config) option parsed into structured data as per module argspec.
+  returned: when I(state) is C(parsed)
+  type: list
+  sample: >
+    This output will always be in the same format as the
+    module argspec.
+"""
+
 from ansible.module_utils.basic import AnsibleModule
 
 from ansible_collections.vyos.vyos.plugins.module_utils.network.vyos.argspec.bgp_global.bgp_global import (
@@ -1423,9 +1472,15 @@ def main():
     """
     module = AnsibleModule(
         argument_spec=Bgp_globalArgs.argument_spec,
-        mutually_exclusive=[],
-        required_if=[],
-        supports_check_mode=False,
+        mutually_exclusive=[["config", "running_config"]],
+        required_if=[
+            ["state", "merged", ["config"]],
+            ["state", "replaced", ["config"]],
+            ["state", "overridden", ["config"]],
+            ["state", "rendered", ["config"]],
+            ["state", "parsed", ["running_config"]],
+        ],
+        supports_check_mode=True,
     )
 
     result = Bgp_global(module).execute_module()