Documentation updates (#18)

* Add documentation for filter plugins.
* Use non-deprecated documentation fragments for modules.
* Bump the collection version to 4.0.1.

galaxy.yml

@@ -9,7 +9,7 @@ namespace: mattclay
 name: aws
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 4.0.0
+version: 4.0.1
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md

plugins/filter/dictfilter.yml

@@ -0,0 +1,29 @@
+DOCUMENTATION:
+  name: dictfilter
+  short_description: filter a dictionary to return only the specified keys
+  description:
+    - The input dictionary will be returned with only the specified keys present.
+  positional: _input, keys
+  options:
+    _input:
+      description: A dictionary to filter.
+      type: dict
+      required: true
+    keys:
+      description: The list of dictionary keys to preserve.
+      type: list
+      elements: str
+      required: true
+
+EXAMPLES: |
+  - '{} | mattclay.aws.dictfilter([]) == {}'
+  - '{} | mattclay.aws.dictfilter(["a"]) == {}'
+  - '{"a": 1} | mattclay.aws.dictfilter(["a"]) == {"a": 1}'
+  - '{"a": 1, "b": 2} | mattclay.aws.dictfilter(["a"]) == {"a": 1}'
+  - '{"a": 1, "b": 2} | mattclay.aws.dictfilter(["a", "b"]) == {"a": 1, "b": 2}'
+  - '{"a": 1, "b": 2} | mattclay.aws.dictfilter(["c"]) == {}'
+
+RETURN:
+  _value:
+    description: The dictionary with only the specified keys present.
+    type: dict

plugins/filter/ec2_az_vpc_route_tables_subnets.yml

@@ -0,0 +1,25 @@
+DOCUMENTATION:
+  name: ec2_az_vpc_route_tables_subnets
+  short_description: generate a list of subnets from availability zones
+  description:
+    - Use the input zones dictionary and provided subnet format string to build a list of subnets.
+  positional: _input, subnet
+  options:
+    _input:
+      description: A dictionary of availability zones. The key is the zone name. The value is unused.
+      type: dict
+      required: true
+    subnet:
+      description: The subnet format string. The placeholder will be replaced with a number representing the availability zone, with ``a`` being ``0``.
+      type: str
+      required: true
+
+EXAMPLES: |
+  - '{"us-east-1a": {}, "us-east-1b": {}} | mattclay.aws.ec2_az_vpc_route_tables_subnets("192.168.%s.0/24") == ["192.168.0.0/24", "192.168.1.0/24"]'
+  - '{"us-east-1f": {}} | mattclay.aws.ec2_az_vpc_route_tables_subnets("192.168.%s.0/24") == ["192.168.5.0/24"]'
+
+RETURN:
+  _value:
+    description: A list of subnets.
+    type: list
+    elements: str

plugins/filter/ec2_az_vpc_subnets.yml

@@ -0,0 +1,29 @@
+DOCUMENTATION:
+  name: ec2_az_vpc_subnets
+  short_description: generate a list of availability zones and subnets
+  description:
+    - Use the input zones dictionary, provided subnet format string and tag name to build a list of availiability zones with subnets.
+  positional: _input, subnet, name
+  options:
+    _input:
+      description: A dictionary of availability zones. The key is the zone name. The value is unused.
+      type: dict
+      required: true
+    subnet:
+      description: The subnet format string. The placeholder will be replaced with a number representing the availability zone, with ``a`` being ``0``.
+      type: str
+      required: true
+    name:
+      description: The name (tag) to apply to the subnet.
+      type: str
+      required: true
+
+EXAMPLES: |
+  - '{"us-east-1a": {}} | mattclay.aws.ec2_az_vpc_subnets("192.168.%s.0/24", "Bob") == [{ "az": "us-east-1a", "cidr": "192.168.0.0/24", "resource_tags": {"Name": "Bob"}}]'
+  - '{"us-east-1f": {}} | mattclay.aws.ec2_az_vpc_subnets("192.168.%s.0/24", "Bob") == [{ "az": "us-east-1f", "cidr": "192.168.5.0/24", "resource_tags": {"Name": "Bob"}}]'
+
+RETURN:
+  _value:
+    description: A list of dictionaries representing the generated availability zones and subnets.
+    type: list
+    elements: dict

plugins/filter/map_format.yml

@@ -0,0 +1,27 @@
+DOCUMENTATION:
+  name: map_format
+  short_description: format a string using
+  description:
+    - Use a dictionary of input values to render the given format string.
+  positional: _input, fmt
+  options:
+    _input:
+      description: A dictionary of values available to be used in the format string.
+      type: dict
+      required: true
+    fmt:
+      description: A format string to render.
+      type: str
+      required: true
+
+EXAMPLES: |
+  - '{} | mattclay.aws.map_format("Hello") == "Hello"'
+  - '{"age": 21} | mattclay.aws.map_format("Hello {name} {age}", name="Bob") == "Hello Bob 21"'
+  - '{"name": "World"} | mattclay.aws.map_format("Hello {name}") == "Hello World"'
+  - '{"name": "World"} | mattclay.aws.map_format("Hello {name}", name="Bob") == "Hello Bob"'
+  - '{"name": "World"} | mattclay.aws.map_format("Hello {name} {0}", 3) == "Hello World 3"'
+
+RETURN:
+  _value:
+    description: Rendered string.
+    type: str

plugins/modules/apigateway.py

@@ -69,8 +69,8 @@
         type: dict
         default: {}
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/aws_account_facts.py

@@ -14,8 +14,8 @@
     - boto3
     - botocore
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/aws_availability_zone_facts.py

@@ -14,8 +14,8 @@
     - boto3
     - botocore
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/cloudwatch_event.py

@@ -46,8 +46,8 @@
         default: enabled
         type: str
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/lambda.py

@@ -107,8 +107,8 @@
         type: list
         elements: str
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/lambda_alias.py

@@ -44,8 +44,8 @@
         type: str
         default: ''
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/lambda_layer.py

@@ -47,8 +47,8 @@
         default: present
         type: str
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/lambda_policy.py

@@ -45,8 +45,8 @@
         required: true
         type: str
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/sqs_event.py

@@ -37,8 +37,8 @@
         default: present
         type: str
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''

plugins/modules/sqs_fifo_queue.py

@@ -36,8 +36,8 @@
         default: present
         type: str
 extends_documentation_fragment:
-    - amazon.aws.aws
-    - amazon.aws.ec2
+    - amazon.aws.common.modules
+    - amazon.aws.region.modules
 '''
 
 EXAMPLES = '''