ali_instance: fix doc formatting (#66086)

lib/ansible/modules/cloud/alicloud/ali_instance.py

@@ -20,156 +20,193 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-ANSIBLE_METADATA = {'metadata_version': '1.1',
+ANSIBLE_METADATA = {
-                    'status': ['preview'],
+    'metadata_version': '1.1',
-                    'supported_by': 'community'}
+    'status': ['preview'],
+    'supported_by': 'community'
+}
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: ali_instance
-version_added: "2.8"
+version_added: '2.8'
-short_description: Create, Start, Stop, Restart or Terminate an Instance in ECS. Add or Remove Instance to/from a Security Group.
+short_description: Create, start, stop, restart or terminate an instance in ECS, add or remove an instance to/from a security group
 description:
-    - Create, start, stop, restart, modify or terminate ecs instances.
+- Create, start, stop, restart, modify or terminate ecs instances.
-    - Add or remove ecs instances to/from security group.
+- Add or remove ecs instances to/from security group.
 options:
-    state:
+  state:
-      description:
-        - The state of the instance after operating.
-      default: 'present'
-      choices: [ 'present', 'running', 'stopped', 'restarted', 'absent' ]
-    availability_zone:
-      description:
-        - Aliyun availability zone ID in which to launch the instance.
-          If it is not specified, it will be allocated by system automatically.
-      aliases: ['alicloud_zone']
-    image_id:
-      description:
-        - Image ID used to launch instances. Required when C(state=present) and creating new ECS instances.
-      aliases: [ 'image' ]
-    instance_type:
-      description:
-        - Instance type used to launch instances. Required when C(state=present) and creating new ECS instances.
-      aliases: ['type']
-    security_groups:
-      description:
-        - A list of security group IDs.
-    vswitch_id:
-      description:
-        - The subnet ID in which to launch the instances (VPC).
-      aliases: ['subnet_id']
-    instance_name:
-      description:
-        - The name of ECS instance, which is a string of 2 to 128 Chinese or English characters. It must begin with an
-          uppercase/lowercase letter or a Chinese character and can contain numerals, ".", "_" or "-".
-          It cannot begin with http:// or https://.
-      aliases: ['name']
     description:
-      description:
+    - The state of the instance after operating.
-        - The description of ECS instance, which is a string of 2 to 256 characters. It cannot begin with http:// or https://.
+    type: str
-    internet_charge_type:
+    default: 'present'
-      description:
+    choices: ['absent', 'present', 'restarted', 'running', 'stopped']
-        - Internet charge type of ECS instance.
+  availability_zone:
-      default: 'PayByBandwidth'
+    description:
-      choices: ['PayByBandwidth', 'PayByTraffic']
+    - Aliyun availability zone ID in which to launch the instance.
-    max_bandwidth_in:
+    - If it is not specified, it will be allocated by system automatically.
-      description:
+    aliases: ['alicloud_zone']
-        - Maximum incoming bandwidth from the public network, measured in Mbps (Megabits per second).
+    type: str
-      default: 200
+  image_id:
-    max_bandwidth_out:
+    description:
-      description:
+    - Image ID used to launch instances.
-        - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second).
+    - Required when I(state=present) and creating new ECS instances.
-      default: 0
+    aliases: ['image']
-    host_name:
+    type: str
-      description:
+  instance_type:
-        - Instance host name.
+    description:
-    password:
+    - Instance type used to launch instances.
-      description:
+    - Required when I(state=present) and creating new ECS instances.
-        - The password to login instance. After rebooting instances, modified password will take effect.
+    aliases: ['type']
-    system_disk_category:
+    type: str
-      description:
+  security_groups:
-        - Category of the system disk.
+    description:
-      default: 'cloud_efficiency'
+    - A list of security group IDs.
-      choices: ['cloud_efficiency', 'cloud_ssd']
+    type: list
-    system_disk_size:
+  vswitch_id:
-      description:
+    description:
-        - Size of the system disk, in GB. The valid values are 40~500.
+    - The subnet ID in which to launch the instances (VPC).
-      default: 40
+    aliases: ['subnet_id']
-    system_disk_name:
+    type: str
-      description:
+  instance_name:
-        - Name of the system disk.
+    description:
-    system_disk_description:
+    - The name of ECS instance, which is a string of 2 to 128 Chinese or English characters.
-      description:
+    - It must begin with an uppercase/lowercase letter or a Chinese character and
-        - Description of the system disk.
+      can contain numerals, ".", "_" or "-". It cannot begin with http:// or https://.
-    count:
+    aliases: ['name']
-      description:
+    type: str
-        - The number of the new instance. An integer value which indicates how many instances that match I(count_tag)
+  description:
-          should be running. Instances are either created or terminated based on this value.
+    description:
-      default: 1
+    - The description of ECS instance, which is a string of 2 to 256 characters.
-    count_tag:
+    - It cannot begin with http:// or https://.
-      description:
+    type: str
-      - I(count) determines how many instances based on a specific tag criteria should be present.
+  internet_charge_type:
-        This can be expressed in multiple ways and is shown in the EXAMPLES section.
+    description:
-        The specified count_tag must already exist or be passed in as the I(instance_tags) option.
+    - Internet charge type of ECS instance.
-        If it is not specified, it will be replaced by I(instance_name).
+    type: str
-    allocate_public_ip:
+    default: 'PayByBandwidth'
-      description:
+    choices: ['PayByBandwidth', 'PayByTraffic']
-        - Whether allocate a public ip for the new instance.
+  max_bandwidth_in:
-      default: False
+    description:
-      aliases: [ 'assign_public_ip' ]
+    - Maximum incoming bandwidth from the public network,
-      type: bool
+      measured in Mbps (Megabits per second).
-    instance_charge_type:
+    default: 200
-      description:
+    type: int
-        - The charge type of the instance.
+  max_bandwidth_out:
-      choices: ['PrePaid', 'PostPaid']
+    description:
-      default: 'PostPaid'
+    - Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second).
-    period:
+    type: int
-      description:
+    default: 0
-        - The charge duration of the instance, in month. Required when C(instance_charge_type=PrePaid).
+  host_name:
-        - The valid value are [1-9, 12, 24, 36].
+    description:
-      default: 1
+    - Instance host name.
-    auto_renew:
+    type: str
-      description:
+  password:
-        - Whether automate renew the charge of the instance.
+    description:
-      type: bool
+    - The password to login instance.
-      default: False
+    - After rebooting instances, modified password will take effect.
-    auto_renew_period:
+    type: str
-      description:
+  system_disk_category:
-        - The duration of the automatic renew the charge of the instance. Required when C(auto_renew=True).
+    description:
-      choices: [1, 2, 3, 6, 12]
+    - Category of the system disk.
-    instance_ids:
+    type: str
-      description:
+    default: 'cloud_efficiency'
-        - A list of instance ids. It is required when need to operate existing instances.
+    choices: ['cloud_efficiency', 'cloud_ssd']
-          If it is specified, I(count) will lose efficacy.
+  system_disk_size:
-    force:
+    description:
-      description:
+    - Size of the system disk, in GB. The valid values are 40~500.
-        - Whether the current operation needs to be execute forcibly.
+    type: int
-      default: False
+    default: 40
-      type: bool
+  system_disk_name:
-    instance_tags:
+    description:
-      description:
+    - Name of the system disk.
-        - A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. C({"key":"value"})
+    type: str
-      aliases: ["tags"]
+  system_disk_description:
-    key_name:
+    description:
-      description:
+    - Description of the system disk.
-        - The name of key pair which is used to access ECS instance in SSH.
+    type: str
-      required: false
+  count:
-      aliases: ['keypair']
+    description:
-    user_data:
+    - The number of the new instance.
-      description:
+    - Indicates how many instances that match I(count_tag) should be running.
-        - User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance.
+    - Instances are either created or terminated based on this value.
-          It only will take effect when launching the new ECS instances.
+    type: int
-      required: false
+    default: 1
+  count_tag:
+    description:
+    - Determines how many instances based on a specific tag criteria should be present.
+    - This can be expressed in multiple ways and is shown in the EXAMPLES section.
+    - The specified count_tag must already exist or be passed in as the I(instance_tags) option.
+    - If it is not specified, it will be replaced by I(instance_name).
+    type: str
+  allocate_public_ip:
+    description:
+    - Whether allocate a public ip for the new instance.
+    default: False
+    aliases: ['assign_public_ip']
+    type: bool
+  instance_charge_type:
+    description:
+    - The charge type of the instance.
+    type: str
+    choices: ['PrePaid', 'PostPaid']
+    default: 'PostPaid'
+  period:
+    description:
+    - The charge duration of the instance, in month.
+    - Required when I(instance_charge_type=PrePaid).
+    - The valid value are [1-9, 12, 24, 36].
+    type: int
+    default: 1
+  auto_renew:
+    description:
+    - Whether automate renew the charge of the instance.
+    type: bool
+    default: False
+  auto_renew_period:
+    description:
+    - The duration of the automatic renew the charge of the instance.
+    - Required when I(auto_renew=True).
+    type: int
+    choices: [1, 2, 3, 6, 12]
+  instance_ids:
+    description:
+    - A list of instance ids. It is required when need to operate existing instances.
+    - If it is specified, I(count) will lose efficacy.
+    type: list
+  force:
+    description:
+    - Whether the current operation needs to be execute forcibly.
+    default: False
+    type: bool
+  instance_tags:
+    description:
+    - A hash/dictionaries of instance tags, to add to the new instance or
+      for starting/stopping instance by tag (C({"key":"value"})).
+    aliases: ['tags']
+    type: dict
+  key_name:
+    description:
+    - The name of key pair which is used to access ECS instance in SSH.
+    type: str
+    required: false
+    aliases: ['keypair']
+  user_data:
+    description:
+    - User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance.
+      It only will take effect when launching the new ECS instances.
+    required: false
+    type: str
 author:
-    - "He Guimin (@xiaozhu36)"
+- "He Guimin (@xiaozhu36)"
 requirements:
-    - "python >= 2.6"
+- "python >= 2.6"
-    - "footmark >= 1.1.16"
+- "footmark >= 1.1.16"
 extends_documentation_fragment:
-    - alicloud
+- alicloud
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # basic provisioning example vpc network
 - name: basic provisioning example
   hosts: localhost
@@ -259,9 +296,9 @@ EXAMPLES = '''
         security_groups: '{{ security_groups }}'
 '''
 
-RETURN = '''
+RETURN = r'''
 instances:
-    description: List of ECS instances
+    description: List of ECS instances.
     returned: always
     type: complex
     contains:
@@ -456,7 +493,7 @@ instances:
             type: str
             sample: 10.0.0.1
         public_ip_address:
-            description: The public IPv4 address assigned to the instance
+            description: The public IPv4 address assigned to the instance.
             returned: always
             type: str
             sample: 43.0.0.1
@@ -502,7 +539,7 @@ instances:
             type: dict
             sample: vpc-0011223344
 ids:
-    description: List of ECS instance IDs
+    description: List of ECS instance IDs.
     returned: always
     type: list
     sample: [i-12345er, i-3245fs]

test/sanity/ignore.txt

@@ -486,9 +486,7 @@ lib/ansible/module_utils/vexata.py future-import-boilerplate
 lib/ansible/module_utils/vexata.py metaclass-boilerplate
 lib/ansible/module_utils/yumdnf.py future-import-boilerplate
 lib/ansible/module_utils/yumdnf.py metaclass-boilerplate
-lib/ansible/modules/cloud/alicloud/ali_instance.py validate-modules:doc-missing-type
 lib/ansible/modules/cloud/alicloud/ali_instance.py validate-modules:doc-required-mismatch
-lib/ansible/modules/cloud/alicloud/ali_instance.py validate-modules:parameter-type-not-in-doc
 lib/ansible/modules/cloud/alicloud/ali_instance_info.py validate-modules:doc-missing-type
 lib/ansible/modules/cloud/alicloud/ali_instance_info.py validate-modules:doc-required-mismatch
 lib/ansible/modules/cloud/alicloud/ali_instance_info.py validate-modules:parameter-type-not-in-doc