Deprecate ec2_vpc module (#20344)

* Deprecate ec2_vpc module

The deprecation of ec2_vpc module has been discussed for
2 years and is causing duplication of effort as changes
are implemented for ec2_vpc rather than for the newer
alternatives

* Improve module deprecation documentation

Update the developing modules documentation with the latest
instructions on how to deprecate a module.

CHANGELOG.md

@@ -26,6 +26,8 @@ Ansible Changes By Release
   the new behaviour.  In 2.4, the default will be to merge and you can enable
   the old overwriting behaviour via the config option.  In 2.5, multiple --tags
   options will be merged with no way to go back to the old behaviour.
+* Modules
+  * ec2_vpc will be deprecated in 2.5
 
 ###New Modules:
 - archive

docs/docsite/rst/dev_guide/developing_modules.rst

@@ -869,6 +869,13 @@ Deprecating and making module aliases
 Starting in 1.8, you can deprecate modules by renaming them with a preceding _, i.e. old_cloud.py to
 _old_cloud.py. This keeps the module available, but hides it from the primary docs and listing.
 
+When deprecating a module, set the `ANSIBLE_METADATA` `status` to `deprecated`.
+In the `DOCUMENTATION` section, add a `deprecated` field along the lines of::
+
+    deprecated: Deprecated in 2.3. Use M(whatmoduletouseinstead) instead.
+
+Add the deprecation to CHANGELOG.md
+
 You can also rename modules and keep an alias to the old name by using a symlink that starts with _.
 This example allows the stat module to be called with fileinfo, making the following examples equivalent::
 

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

@@ -14,7 +14,7 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
-ANSIBLE_METADATA = {'status': ['stableinterface'],
+ANSIBLE_METADATA = {'status': ['deprecated'],
                     'supported_by': 'committer',
                     'version': '1.0'}
 
@@ -25,6 +25,10 @@ short_description: configure AWS virtual private clouds
 description:
     - Create or terminates AWS virtual private clouds.  This module has a dependency on python-boto.
 version_added: "1.4"
+deprecated: >-
+  Deprecated in 2.3. Use M(epc_vpc_net) along with supporting modules including
+  M(ec2_vpc_igw), M(ec2_vpc_route_table), M(ec2_vpc_subnet), M(ec2_vpc_dhcp_options),
+  M(ec2_vpc_nat_gateway), M(ec2_vpc_nacl).
 options:
   cidr_block:
     description:
@@ -400,7 +404,6 @@ def create_vpc(module, vpc_conn):
     vpc_conn.modify_vpc_attribute(vpc.id, enable_dns_support=dns_support)
     vpc_conn.modify_vpc_attribute(vpc.id, enable_dns_hostnames=dns_hostnames)
 
-
     # Process all subnet properties
     if subnets is not None:
         if not isinstance(subnets, list):