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()
```

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -201,9 +201,17 @@ The following fields can be used and are all required unless specified otherwise
 :author:
   Name of the module author in the form ``First Last (@GitHubID)``. Use a multi-line list if there is more than one author.
 :deprecated:
-  If this module is deprecated, detail when that happened, and what to use instead, e.g.
-  `Deprecated in 2.3. Use M(whatmoduletouseinstead) instead.`
-  Ensure `CHANGELOG.md` is updated to reflect this.
+  If a module is deprecated it must be:
+
+  * Mentioned in ``CHANGELOG``
+  * Referenced in the ``porting_guide_x.y.rst``
+  * File should be renamed to start with an ``_``
+  * ``ANSIBLE_METADATA`` must contain ``status: ['deprecated']``
+  * Following values must be set:
+
+  :removed_in: A `string`, such as ``"2.9"``, which represents the version of Ansible this module will replaced with docs only module stub.
+  :why: Optional string that used to detail why this has been removed.
+  :alternative: Inform users they should do instead, i.e. ``Use M(whatmoduletouseinstead) instead.``.
 :options:
   One per module argument:
 

docs/docsite/rst/dev_guide/testing_validate-modules.rst

@@ -63,8 +63,8 @@ Errors
   **1xx**   **Locations**
   101       Interpreter line is not ``#!/usr/bin/python``
   102       Interpreter line is not ``#!powershell``
-  103       Did not find a call to ``main()``
-  104       Call to ``main()`` not the last line
+  103       Did not find a call to ``main()`` (or ``removed_module()`` in the case of deprecated & docs only modules)
+  104       Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules)
   105       GPLv3 license header not found
   106       Import found before documentation variables. All imports must appear below
             ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA``

docs/docsite/rst/porting_guide_2.5.rst

@@ -76,7 +76,17 @@ Modules removed
 
 The following modules no longer exist:
 
-* None
+* :ref:`nxos_mtu <nxos_mtu>` use :ref:`nxos_system <nxos_system>`'s ``system_mtu`` option or :ref:`nxos_interface <nxos_interface>` instead
+* :ref:`cl_interface_policy <cl_interface_policy>` use :ref:`nclu <nclu>` instead
+* :ref:`cl_bridge <cl_bridge>` use :ref:`nclu <nclu>` instead
+* :ref:`cl_img_install <cl_img_install>` use :ref:`nclu <nclu>` instead
+* :ref:`cl_ports <cl_ports>` use :ref:`nclu <nclu>` instead
+* :ref:`cl_license <cl_license>` use :ref:`nclu <nclu>` instead
+* :ref:`cl_interface <cl_interface>` use :ref:`nclu <nclu>` instead
+* :ref:`cl_bond <cl_bond>` use :ref:`nclu <nclu>` instead
+* :ref:`ec2_vpc <ec_vpc>` use :ref:`ec2_vpc_net <ec2_vpc_net>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet>`, :ref:`ec2_vpc_dhcp_options <ec2_vpc_dhcp_options>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl>` instead.
+* :ref:`ec2_ami_search <ec2_ami_search` use :ref:`ec2_ami_facts <ec2_ami_facts>` instead
+* :ref:`docker <docker>` use :ref:`docker_container <docker_container>` and :ref:`docker_image <docker_image>` instead
 
 Deprecation notices
 -------------------

docs/templates/plugin.rst.j2

@@ -34,7 +34,7 @@ DEPRECATED
 ----------
 
 {# use unknown here? skip the fields? #}
-:In: version: @{ deprecated['version'] | default('') | string | convert_symbols_to_format }@
+:Removed in Ansible: version: @{ deprecated['removed_in'] | default('') | string | convert_symbols_to_format }@
 :Why: @{ deprecated['why'] | default('') | convert_symbols_to_format }@
 :Alternative: @{ deprecated['alternative'] | default('')|  convert_symbols_to_format }@