[Part #3] Ensures the modules documentation follows the correct forma…

…ts (#2082) (#2247) This is a backport of PR #2082 as merged into main (b47d1cf). SUMMARY ISSUE TYPE Bugfix Pull Request Docs Pull Request Feature Pull Request New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Mark Chappell
ansible-collections · Aug 28, 2024 · dbcb0cc · dbcb0cc
1 parent 956a220
commit dbcb0cc
Show file tree

Hide file tree

Showing 15 changed files with 129 additions and 127 deletions.
diff --git a/changelogs/fragments/documentation_update_3.yml b/changelogs/fragments/documentation_update_3.yml
@@ -0,0 +1,2 @@
+trivial:
+  - "Part #3 - Ensures the modules documentation follows the correct formats (see also https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#semantic-markup-within-module-documentation)."
diff --git a/plugins/modules/ec2_vol.py b/plugins/modules/ec2_vol.py
@@ -11,12 +11,12 @@
 short_description: Create and attach a volume, return volume ID and device map
 description:
   - Creates an EBS volume and optionally attaches it to an instance.
-  - If both I(instance) and I(name) are given and the instance has a device at the device name, then no volume is created and no attachment is made.
+  - If both O(instance) and O(name) are given and the instance has a device at the device name, then no volume is created and no attachment is made.
 options:
   instance:
     description:
       - Instance ID if you wish to attach the volume.
-      - Set to C(None) to detach the volume.
+      - Set to V(None) to detach the volume.
     type: str
   name:
     description:
@@ -32,9 +32,9 @@
     type: int
   volume_type:
     description:
-      - Type of EBS volume; C(standard) (magnetic), C(gp2) (SSD), C(gp3) (SSD), C(io1) (Provisioned IOPS), C(io2) (Provisioned IOPS),
-        C(st1) (Throughput Optimized HDD), C(sc1) (Cold HDD).
-      - C(standard) is the old EBS default and continues to remain the Ansible default for backwards compatibility.
+      - Type of EBS volume; V(standard) (magnetic), V(gp2) (SSD), V(gp3) (SSD), V(io1) (Provisioned IOPS), V(io2) (Provisioned IOPS),
+        V(st1) (Throughput Optimized HDD), V(sc1) (Cold HDD).
+      - V(standard) is the old EBS default and continues to remain the Ansible default for backwards compatibility.
     default: standard
     choices: ['standard', 'gp2', 'io1', 'st1', 'sc1', 'gp3', 'io2']
     type: str
@@ -72,15 +72,15 @@
   state:
     description:
       - Whether to ensure the volume is present or absent.
-      - I(state=list) was deprecated in release 1.1.0 and is no longer available
+      - O(state=list) was deprecated in release 1.1.0 and is no longer available
         with release 4.0.0.
-      - The C(list) functionality has been moved to a dedicated module M(amazon.aws.ec2_vol_info).
+      - The V(list) functionality has been moved to a dedicated module M(amazon.aws.ec2_vol_info).
     default: present
     choices: ['absent', 'present']
     type: str
   modify_volume:
     description:
-      - The volume won't be modified unless this key is C(true).
+      - The volume won't be modified unless this key is V(true).
     type: bool
     default: false
     version_added: 1.4.0
@@ -93,7 +93,7 @@
     version_added: 1.4.0
   multi_attach:
     description:
-      - If set to C(true), Multi-Attach will be enabled when creating the volume.
+      - If set to V(true), Multi-Attach will be enabled when creating the volume.
       - When you create a new volume, Multi-Attach is disabled by default.
       - This parameter is supported with io1 and io2 volumes only.
     type: bool
@@ -107,7 +107,7 @@
 author:
   - "Lester Wade (@lwade)"
 notes:
-  - Support for I(purge_tags) was added in release 1.5.0.
+  - Support for O(purge_tags) was added in release 1.5.0.
 extends_documentation_fragment:
   - amazon.aws.common.modules
   - amazon.aws.region.modules
@@ -205,22 +205,22 @@
 
 RETURN = r"""
 device:
-    description: device name of attached volume
+    description: Device name of attached volume.
     returned: when success
     type: str
     sample: "/dev/sdf"
 volume_id:
-    description: the id of volume
+    description: The id of volume.
     returned: when success
     type: str
     sample: "vol-35b333d9"
 volume_type:
-    description: the volume type
+    description: The volume type.
     returned: when success
     type: str
     sample: "standard"
 volume:
-    description: a dictionary containing detailed attributes of the volume
+    description: A dictionary containing detailed attributes of the volume.
     returned: when success
     type: dict
     contains:

diff --git a/plugins/modules/ec2_vpc_dhcp_option.py b/plugins/modules/ec2_vpc_dhcp_option.py
@@ -68,7 +68,7 @@
   inherit_existing:
     description:
       - For any DHCP options not specified in these parameters, whether to
-        inherit them from the options set already applied to I(vpc_id), or to
+        inherit them from the options set already applied to O(vpc_id), or to
         reset them to be empty.
     type: bool
     default: false
@@ -87,7 +87,7 @@
     choices: [ 'absent', 'present' ]
     type: str
 notes:
-  - Support for I(purge_tags) was added in release 2.0.0.
+  - Support for O(purge_tags) was added in release 2.0.0.
 extends_documentation_fragment:
   - amazon.aws.common.modules
   - amazon.aws.region.modules

diff --git a/plugins/modules/ec2_vpc_endpoint.py b/plugins/modules/ec2_vpc_endpoint.py
@@ -29,15 +29,15 @@
   vpc_endpoint_subnets:
     description:
       - The list of subnets to attach to the endpoint.
-      - Requires I(vpc_endpoint_type=GatewayLoadBalancer) or I(vpc_endpoint_type=Interface).
+      - Requires O(vpc_endpoint_type=GatewayLoadBalancer) or O(vpc_endpoint_type=Interface).
     required: false
     type: list
     elements: str
     version_added: 2.1.0
   vpc_endpoint_security_groups:
     description:
       - The list of security groups to attach to the endpoint.
-      - Requires I(vpc_endpoint_type=GatewayLoadBalancer) or I(vpc_endpoint_type=Interface).
+      - Requires O(vpc_endpoint_type=GatewayLoadBalancer) or O(vpc_endpoint_type=Interface).
     required: false
     type: list
     elements: str
@@ -59,23 +59,23 @@
     type: json
   state:
     description:
-      - C(present) to ensure resource is created.
-      - C(absent) to remove resource.
+      - V(present) to ensure resource is created.
+      - V(absent) to remove resource.
     required: false
     default: present
     choices: [ "present", "absent" ]
     type: str
   wait:
     description:
-      - When specified, will wait for status to reach C(available) for I(state=present).
+      - When specified, will wait for status to reach available for O(state=present).
       - Unfortunately this is ignored for delete actions due to a difference in
         behaviour from AWS.
     required: false
     default: false
     type: bool
   wait_timeout:
     description:
-      - Used in conjunction with I(wait).
+      - Used in conjunction with O(wait).
       - Number of seconds to wait for status.
       - Unfortunately this is ignored for delete actions due to a difference in
         behaviour from AWS.
@@ -87,14 +87,14 @@
       - List of one or more route table IDs to attach to the endpoint.
       - A route is added to the route table with the destination of the
         endpoint if provided.
-      - Route table IDs are only valid for C(Gateway) endpoints.
+      - Route table IDs are only valid for Gateway endpoints.
     required: false
     type: list
     elements: str
   vpc_endpoint_id:
     description:
       - One or more VPC endpoint IDs to remove from the AWS account.
-      - Required if I(state=absent).
+      - Required if O(state=absent).
     required: false
     type: str
   client_token:
@@ -105,9 +105,9 @@
 author:
   - Karen Cheng (@Etherdaemon)
 notes:
-  - Support for I(tags) and I(purge_tags) was added in release 1.5.0.
-  - The C(policy_file) paramater was removed in release 6.0.0 please use the
-    I(policy) option and a file lookup instead.
+  - Support for O(tags) and I(purge_tags) was added in release 1.5.0.
+  - The I(policy_file) paramater was removed in release 6.0.0 please use the
+    O(policy) option and the P(ansible.builtin.file#lookup) lookup plugin instead.
 extends_documentation_fragment:
   - amazon.aws.common.modules
   - amazon.aws.region.modules
@@ -150,7 +150,7 @@
 
 RETURN = r"""
 endpoints:
-  description: The resulting endpoints from the module call
+  description: The resulting endpoints from the module call.
   returned: success
   type: list
   elements: dict

diff --git a/plugins/modules/ec2_vpc_endpoint_info.py b/plugins/modules/ec2_vpc_endpoint_info.py
@@ -30,8 +30,8 @@
   - amazon.aws.region.modules
   - amazon.aws.boto3
 notes:
-  - Support for the C(query) parameter was dropped in release 6.0.0.  This module now only queries
-    for endpoints.  Information about endpoint services can be retrieved using the
+  - Support for the I(query) parameter was dropped in release 6.0.0.  This module now only queries
+    for endpoints. Information about endpoint services can be retrieved using the
     M(amazon.aws.ec2_vpc_endpoint_service_info) module.
 """
 

diff --git a/plugins/modules/ec2_vpc_igw.py b/plugins/modules/ec2_vpc_igw.py
@@ -10,7 +10,7 @@
 version_added: 1.0.0
 short_description: Manage an AWS VPC Internet gateway
 description:
-    - Manage an AWS VPC Internet gateway
+    - Manage an AWS VPC Internet gateway.
 author: Robert Estelle (@erydo)
 options:
   internet_gateway_id:
@@ -21,33 +21,33 @@
     type: str
   vpc_id:
     description:
-      - The VPC ID for the VPC to attach (when state=present)
-      - VPC ID can also be provided to find the internet gateway to manage that the VPC is attached to
+      - The VPC ID for the VPC to attach (when O(state=present)).
+      - VPC ID can also be provided to find the internet gateway to manage that the VPC is attached to.
     required: false
     type: str
   state:
     description:
-      - Create or terminate the IGW
+      - Create or terminate the IGW.
     default: present
     choices: [ 'present', 'absent' ]
     type: str
   force_attach:
     version_added: 7.0.0
     description:
-      - Force attaching VPC to I(vpc_id).
-      - Setting this option to true will detach an existing VPC attachment and attach to the supplied I(vpc_id).
-      - Ignored when I(state=absent).
-      - I(vpc_id) must be specified when I(force_attach) is true
+      - Force attaching VPC to O(vpc_id).
+      - Setting this option to true will detach an existing VPC attachment and attach to the supplied O(vpc_id).
+      - Ignored when O(state=absent).
+      - O(vpc_id) must be specified when O(force_attach=true).
     default: false
     type: bool
   detach_vpc:
     version_added: 7.0.0
     description:
-      - Remove attached VPC from gateway
+      - Remove attached VPC from gateway.
     default: false
     type: bool
 notes:
-- Support for I(purge_tags) was added in release 1.3.0.
+- Support for O(purge_tags) was added in release 1.3.0.
 extends_documentation_fragment:
   - amazon.aws.common.modules
   - amazon.aws.region.modules
@@ -118,20 +118,20 @@
 gateway_id:
   description: The unique identifier for the Internet Gateway.
   type: str
-  returned: I(state=present)
+  returned: O(state=present)
   sample:
     gateway_id: "igw-XXXXXXXX"
 tags:
   description: The tags associated the Internet Gateway.
   type: dict
-  returned: I(state=present)
+  returned: O(state=present)
   sample:
     tags:
       "Ansible": "Test"
 vpc_id:
   description: The VPC ID associated with the Internet Gateway.
   type: str
-  returned: I(state=present)
+  returned: O(state=present)
   sample:
     vpc_id: "vpc-XXXXXXXX"
 """

diff --git a/plugins/modules/ec2_vpc_igw_info.py b/plugins/modules/ec2_vpc_igw_info.py
@@ -27,8 +27,8 @@
   convert_tags:
     description:
       - Convert tags from boto3 format (list of dictionaries) to the standard dictionary format.
-      - Prior to release 4.0.0 this defaulted to C(False).
-    default: True
+      - Prior to release 4.0.0 this defaulted to V(false).
+    default: true
     type: bool
     version_added: 1.3.0
 extends_documentation_fragment:
@@ -67,7 +67,7 @@
     description: True if listing the internet gateways succeeds.
     type: bool
     returned: always
-    sample: "false"
+    sample: false
 internet_gateways:
     description: The internet gateways for the account.
     returned: always

diff --git a/plugins/modules/ec2_vpc_nat_gateway.py b/plugins/modules/ec2_vpc_nat_gateway.py
@@ -43,12 +43,12 @@
   eip_address:
     description:
       - The elastic IP address of the EIP you want attached to this NAT Gateway.
-        If this is not passed and the allocation_id is not passed,
+        If this is not passed and the O(allocation_id) is not passed,
         an EIP is generated for this NAT Gateway.
     type: str
   if_exist_do_not_create:
     description:
-      - if a NAT Gateway exists already in the subnet_id, then do not create a new one.
+      - If a NAT Gateway exists already in the O(subnet_id), then do not create a new one.
     required: false
     default: false
     type: bool
@@ -77,11 +77,11 @@
     type: str
   default_create:
     description:
-      - When I(default_create=True) and I(eip_address) has been set, but not yet
+      - When O(default_create=true) and O(eip_address) has been set, but not yet
         allocated, the NAT gateway is created and a new EIP is automatically allocated.
-      - When I(default_create=False) and I(eip_address) has been set, but not yet
+      - When O(default_create=false) and O(eip_address) has been set, but not yet
         allocated, the module will fail.
-      - If I(eip_address) has not been set, this parameter has no effect.
+      - If O(eip_address) has not been set, this parameter has no effect.
     default: false
     type: bool
     version_added: 6.2.0
@@ -91,7 +91,7 @@
   - Karen Cheng (@Etherdaemon)
   - Alina Buzachis (@alinabuzachis)
 notes:
-  - Support for I(tags) and I(purge_tags) was added in release 1.4.0.
+  - Support for O(tags) and O(purge_tags) was added in release 1.4.0.
 extends_documentation_fragment:
   - amazon.aws.common.modules
   - amazon.aws.region.modules
@@ -205,22 +205,22 @@
     sample: public
 create_time:
   description: The ISO 8601 date time format in UTC.
-  returned: In all cases.
+  returned: always
   type: str
   sample: "2016-03-05T05:19:20.282000+00:00'"
 nat_gateway_id:
-  description: id of the VPC NAT Gateway
-  returned: In all cases.
+  description: Id of the VPC NAT Gateway.
+  returned: always
   type: str
   sample: "nat-0d1e3a878585988f8"
 subnet_id:
-  description: id of the Subnet
-  returned: In all cases.
+  description: Id of the Subnet.
+  returned: always
   type: str
   sample: "subnet-12345"
 state:
   description: The current state of the NAT Gateway.
-  returned: In all cases.
+  returned: always
   type: str
   sample: "available"
 tags:
@@ -231,13 +231,13 @@
     tags:
         "Ansible": "Test"
 vpc_id:
-  description: id of the VPC.
-  returned: In all cases.
+  description: Id of the VPC.
+  returned: always
   type: str
   sample: "vpc-12345"
 nat_gateway_addresses:
   description: List of dictionaries containing the public_ip, network_interface_id, private_ip, and allocation_id.
-  returned: In all cases.
+  returned: always
   type: complex
   contains:
     allocation_id:

diff --git a/plugins/modules/ec2_vpc_nat_gateway_info.py b/plugins/modules/ec2_vpc_nat_gateway_info.py
@@ -9,7 +9,7 @@
 short_description: Retrieves AWS VPC Managed Nat Gateway details using AWS methods
 version_added: 1.0.0
 description:
-  - Gets various details related to AWS VPC Managed Nat Gateways
+  - Gets various details related to AWS VPC Managed Nat Gateways.
 options:
   nat_gateway_ids:
     description: