VMware: Deprecate vsphere_guest module (#35648)

This change deprecates vsphere_guest in favor of vmware_guest and other
related modules.

The major reasons behind deprecation are -

- Pysphere - Unofficial Python bindings of vCenter deprecated in the year 2013.
- VMware provides official Python bindings for vCenter, which is used in vmware_guest.
- vcsim - simulator used in integration testing of vmware module does not support PySphere
  APIs, which makes it more difficult to test vsphere_guest.

Please see [deprecation plan](https://github.com/ansible/community/wiki/VMware%3A-vsphere_guest_deprecation)

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/modules/cloud/vmware/_vsphere_guest.py

@@ -8,7 +8,7 @@ __metaclass__ = type
 
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
+                    'status': ['deprecated'],
                     'supported_by': 'community'}
 
 
@@ -16,6 +16,10 @@ DOCUMENTATION = '''
 ---
 module: vsphere_guest
 short_description: Create/delete/manage a guest VM through VMware vSphere.
+deprecated:
+    removed_in: "2.9"
+    why: "Replaced by M(vmware_guest) module. Also, 'Pysphere' is deprecated in favor of VMware's Official Python bindings - 'Pyvmomi'."
+    alternative: Use M(vmware_guest) and other vmware guest related modules instead.
 description:
      - Create/delete/reconfigure a guest VM through VMware vSphere. This module has a dependency on pysphere >= 1.7
 version_added: "1.6"
@@ -1768,6 +1772,8 @@ def main():
         ],
     )
 
+    module.deprecate("The 'vsphere_guest' module has been deprecated. Use 'vmware_guest' instead.", version=2.9)
+
     if not HAS_PYSPHERE:
         module.fail_json(msg='pysphere module required')