Improve aws_ec2 plugin documentation (#37689)

* Better formatting
* More examples

lib/ansible/plugins/inventory/aws_ec2.py

@@ -56,39 +56,44 @@ DOCUMENTATION = '''
 '''
 
 EXAMPLES = '''
-simple_config_file:
+plugin: aws_ec2
-
+boto_profile: aws_profile
-    plugin: aws_ec2
+regions: # populate inventory with instances in these regions
-    boto_profile: aws_profile
+  - us-east-1
-    regions: # populate inventory with instances in these regions
+  - us-east-2
-      - us-east-1
+filters:
-      - us-east-2
+  # all instances with their `Environment` tag set to `dev`
-    filters:
+  tag:Environment: dev
-      # all instances with their `Environment` tag set to `dev`
+  # all dev and QA hosts
-      tag:Environment: dev
+  tag:Environment:
-      # all dev and QA hosts
+    - dev
-      tag:Environment:
+    - qa
-        - dev
+  instance.group-id: sg-xxxxxxxx
-        - qa
+# ignores 403 errors rather than failing
-      instance.group-id: sg-xxxxxxxx
+strict_permissions: False
-    # ignores 403 errors rather than failing
+hostnames:
-    strict_permissions: False
+  - tag:Name=Tag1,Name=Tag2  # return specific hosts only
-    hostnames:
+  - tag:CustomDNSName
-      - tag:Name=Tag1,Name=Tag2
+  - dns-name
-      - tag:CustomDNSName
-      - dns-name
-
-    # constructed features may be used to create custom groups
-    strict: False
-    keyed_groups:
-      - prefix: arch
-        key: 'architecture'
-        value: 'x86_64'
-      - prefix: tag
-        key: tags
-        value:
-          "Name": "Test"
 
+# keyed_groups may be used to create custom groups
+strict: False
+keyed_groups:
+  # add e.g. x86_64 hosts to an arch_x86_64 group
+  - prefix: arch
+    key: 'architecture'
+  # add hosts to tag_Name_Value groups for each Name/Value tag pair
+  - prefix: tag
+    key: tags
+  # add hosts to e.g. instance_type_z3_tiny
+  - prefix: instance_type
+    key: instance_type
+  # create security_groups_sg_abcd1234 group for each SG
+  - key: 'security_groups|json_query("[].group_id")'
+    prefix: 'security_groups'
+  # create a group for each value of the Application tag
+  - key: tag.Application
+    separator: ''
 '''
 
 from ansible.errors import AnsibleError, AnsibleParserError