Module deprecation: docs, scheme and tests (#34100)

Enforce module deprecation.
After module has reached the end of it's deprecation cycle we will replace it with a docs stub.

* Replace deprecated modules with docs-only sub
* Use of deprecated past deprecation cycle gives meaningful message (see examples below)
* Enforce documentation.deprecation dict via `schema.py`
* Update `ansible-doc` and web docs to display documentation.deprecation
* Document that structure in `dev_guide`
* Ensure that all modules starting with `_` have a `deprecation:` block
* Ensure `deprecation:` block is only used on modules that start with `_`
* `removed_in` A string which represents when this module needs **deleting**
* CHANGELOG.md and porting_guide_2.5.rst list removed modules as well as alternatives
* CHANGELOG.md links to porting guide index

To ensure that meaningful messages are given to the user if they try to use a module at the end of it's deprecation cycle we enforce the module to contain:
```python
if __name__ == '__main__':
    removed_module()
```

lib/ansible/modules/cloud/amazon/_ec2_ami_search.py

@@ -16,7 +16,10 @@ DOCUMENTATION = '''
 ---
 module: ec2_ami_search
 short_description: Retrieve AWS AMI information for a given operating system.
-deprecated: "Use M(ec2_ami_find) instead."
+deprecated:
+  removed_in: "2.2"
+  why: Various AWS modules have been combined and replaced with M(ec2_ami_facts).
+  alternative: Use M(ec2_ami_find) instead.
 version_added: "1.6"
 description:
   - Look up the most recent AMI on AWS for a given operating system.
@@ -84,124 +87,7 @@ EXAMPLES = '''
       key_name: mykey
 '''
 
-import csv
-
-from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils.urls import fetch_url
-
-
-SUPPORTED_DISTROS = ['ubuntu']
-
-AWS_REGIONS = ['ap-northeast-1',
-               'ap-southeast-1',
-               'ap-northeast-2',
-               'ap-southeast-2',
-               'ap-south-1',
-               'ca-central-1',
-               'eu-central-1',
-               'eu-west-1',
-               'eu-west-2',
-               'sa-east-1',
-               'us-east-1',
-               'us-east-2',
-               'us-west-1',
-               'us-west-2',
-               "us-gov-west-1"]
-
-
-def get_url(module, url):
-    """ Get url and return response """
-
-    r, info = fetch_url(module, url)
-    if info['status'] != 200:
-        # Backwards compat
-        info['status_code'] = info['status']
-        module.fail_json(**info)
-    return r
-
-
-def ubuntu(module):
-    """ Get the ami for ubuntu """
-
-    release = module.params['release']
-    stream = module.params['stream']
-    store = module.params['store']
-    arch = module.params['arch']
-    region = module.params['region']
-    virt = module.params['virt']
-
-    url = get_ubuntu_url(release, stream)
-
-    req = get_url(module, url)
-    reader = csv.reader(req, delimiter='\t')
-    try:
-        ami, aki, ari, tag, serial = lookup_ubuntu_ami(reader, release, stream,
-                                                       store, arch, region, virt)
-        module.exit_json(changed=False, ami=ami, aki=aki, ari=ari, tag=tag,
-                         serial=serial)
-    except KeyError:
-        module.fail_json(msg="No matching AMI found")
-
-
-def lookup_ubuntu_ami(table, release, stream, store, arch, region, virt):
-    """ Look up the Ubuntu AMI that matches query given a table of AMIs
-
-        table: an iterable that returns a row of
-               (release, stream, tag, serial, region, ami, aki, ari, virt)
-        release: ubuntu release name
-        stream: 'server' or 'desktop'
-        store: 'ebs', 'ebs-io1', 'ebs-ssd' or 'instance-store'
-        arch: 'i386' or 'amd64'
-        region: EC2 region
-        virt: 'paravirtual' or 'hvm'
-
-        Returns (ami, aki, ari, tag, serial)"""
-    expected = (release, stream, store, arch, region, virt)
-
-    for row in table:
-        (actual_release, actual_stream, tag, serial,
-            actual_store, actual_arch, actual_region, ami, aki, ari,
-            actual_virt) = row
-        actual = (actual_release, actual_stream, actual_store, actual_arch,
-                  actual_region, actual_virt)
-        if actual == expected:
-            # aki and ari are sometimes blank
-            if aki == '':
-                aki = None
-            if ari == '':
-                ari = None
-            return (ami, aki, ari, tag, serial)
-
-    raise KeyError()
-
-
-def get_ubuntu_url(release, stream):
-    url = "https://cloud-images.ubuntu.com/query/%s/%s/released.current.txt"
-    return url % (release, stream)
-
-
-def main():
-    arg_spec = dict(
-        distro=dict(required=True, choices=SUPPORTED_DISTROS),
-        release=dict(required=True),
-        stream=dict(required=False, default='server',
-                    choices=['desktop', 'server']),
-        store=dict(required=False, default='ebs',
-                   choices=['ebs', 'ebs-io1', 'ebs-ssd', 'instance-store']),
-        arch=dict(required=False, default='amd64',
-                  choices=['i386', 'amd64']),
-        region=dict(required=False, default='us-east-1', choices=AWS_REGIONS),
-        virt=dict(required=False, default='paravirtual',
-                  choices=['paravirtual', 'hvm']),
-    )
-    module = AnsibleModule(argument_spec=arg_spec)
-    distro = module.params['distro']
-
-    if distro == 'ubuntu':
-        ubuntu(module)
-    else:
-        module.fail_json(msg="Unsupported distro: %s" % distro)
-
+from ansible.module_utils.common.removed import removed_module
 
 if __name__ == '__main__':
-    main()
+    removed_module()