XenServer: Update docs with recent changes in XenAPI python lib and branding (#63728)

- xenserver module_util: XenAPI lib import error message handling is now
   ported to missing_required_lib(). Updated unit tests.
 - xenserver_guest, xenserver_guest_info, xenserver_guest_powerstate modules:
   docs are updated to reflect recent changes in availability of XenAPI lib
   on PyPI.
 - xenserver_guest, xenserver_guest_info, xenserver_guest_powerstate modules:
   docs are updated to reflect recent Citrix rebranding of XenServer. Broken
   URLs to external resources are fixed.
 - xenserver_guest, xenserver_guest_info, xenserver_guest_powerstate modules:
   more tested platforms are mentioned in docs.

lib/ansible/module_utils/xenserver.py

@@ -9,15 +9,17 @@ __metaclass__ = type
 import atexit
 import time
 import re
+import traceback
 
-HAS_XENAPI = False
+XENAPI_IMP_ERR = None
 try:
     import XenAPI
     HAS_XENAPI = True
 except ImportError:
-    pass
+    HAS_XENAPI = False
+    XENAPI_IMP_ERR = traceback.format_exc()
 
-from ansible.module_utils.basic import env_fallback
+from ansible.module_utils.basic import env_fallback, missing_required_lib
 from ansible.module_utils.common.network import is_mac
 from ansible.module_utils.ansible_release import __version__ as ANSIBLE_VERSION
 
@@ -847,9 +849,7 @@ class XenServerObject(object):
             module: Reference to Ansible module object.
         """
         if not HAS_XENAPI:
-            module.fail_json(changed=False, msg=("XenAPI Python library is required for this module! "
+            module.fail_json(changed=False, msg=missing_required_lib("XenAPI"), exception=XENAPI_IMP_ERR)
-                                                 "Please download XenServer SDK and copy XenAPI.py to your Python site-packages. "
-                                                 "Check Notes section in module documentation for more info."))
 
         self.module = module
         self.xapi_session = XAPI.connect(module)

lib/ansible/modules/cloud/xenserver/xenserver_guest.py

@@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 DOCUMENTATION = r'''
 ---
 module: xenserver_guest
-short_description: Manages virtual machines running on Citrix XenServer host or pool
+short_description: Manages virtual machines running on Citrix Hypervisor/XenServer host or pool
 description: >
    This module can be used to create new virtual machines from templates or other virtual machines,
    modify various virtual machine components like network and disk, rename a virtual machine and
@@ -24,9 +24,10 @@ author:
 - Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
 notes:
 - Minimal supported version of XenServer is 5.6.
-- Module was tested with XenServer 6.5, 7.1 and 7.2.
+- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
-- 'XenAPI Python library can be acquired from XenServer SDK (downloadable from Citrix website) or by running C(pip install XenAPI) (possibly very old
+- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside
-   version, not compatible with Python 3.x). Latest version can also be acquired from GitHub:
+   Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your
+   Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub:
    https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI.py'
 - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are
    accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
@@ -36,16 +37,16 @@ notes:
   XenServer 7.0 or newer for Windows guests by using official XenServer Guest agent support for network configuration. The module will try to
   detect if such support is available and utilize it, else it will use a custom method of configuration via xenstore. Since XenServer Guest
   agent only support None and Static types of network configuration, where None means DHCP configured interface, C(networks.type) and C(networks.type6)
-  values C(none) and C(dhcp) have same effect.
+  values C(none) and C(dhcp) have same effect. More info here:
-  More info here: https://xenserver.org/blog/entry/set-windows-guest-vm-static-ip-address-in-xenserver.html'
+  https://www.citrix.com/community/citrix-developer/citrix-hypervisor-developer/citrix-hypervisor-developing-products/citrix-hypervisor-staticip.html'
 - 'On platforms without official support for network configuration inside a guest OS, network parameters will be written to xenstore
   C(vm-data/networks/<vif_device>) key. Parameters can be inspected by using C(xenstore ls) and C(xenstore read) tools on \*nix guests or trough
   WMI interface on Windows guests. They can also be found in VM facts C(instance.xenstore_data) key as returned by the module. It is up to the user
   to implement a boot time scripts or custom agent that will read the parameters from xenstore and configure network with given parameters.
   Take note that for xenstore data to become available inside a guest, a VM restart is needed hence module will require VM restart if any
   parameter is changed. This is a limitation of XenAPI and xenstore. Considering these limitations, network configuration trough xenstore is most
-  useful for bootstraping newly deployed VMs, much less for reconfiguring existing ones.
+  useful for bootstraping newly deployed VMs, much less for reconfiguring existing ones. More info here:
-  More info here: https://support.citrix.com/article/CTX226713'
+  https://support.citrix.com/article/CTX226713'
 requirements:
 - python >= 2.6
 - XenAPI

lib/ansible/modules/cloud/xenserver/xenserver_guest_info.py

@@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 DOCUMENTATION = r'''
 ---
 module: xenserver_guest_info
-short_description: Gathers information for virtual machines running on Citrix XenServer host or pool
+short_description: Gathers information for virtual machines running on Citrix Hypervisor/XenServer host or pool
 description: >
    This module can be used to gather essential VM facts.
 version_added: '2.8'
@@ -22,9 +22,10 @@ author:
 - Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
 notes:
 - Minimal supported version of XenServer is 5.6.
-- Module was tested with XenServer 6.5, 7.1 and 7.2.
+- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
-- 'XenAPI Python library can be acquired from XenServer SDK (downloadable from Citrix website) or by running C(pip install XenAPI) (possibly very old
+- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside
-   version, not compatible with Python 3.x). Latest version can also be acquired from GitHub:
+   Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your
+   Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub:
    https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI.py'
 - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are
    accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'
@@ -206,6 +207,7 @@ def main():
                                ['name', 'uuid'],
                            ],
                            )
+
     if module._name == 'xenserver_guest_facts':
         module.deprecate("The 'xenserver_guest_facts' module has been renamed to 'xenserver_guest_info'", version='2.13')
 

lib/ansible/modules/cloud/xenserver/xenserver_guest_powerstate.py

@@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 DOCUMENTATION = r'''
 ---
 module: xenserver_guest_powerstate
-short_description: Manages power states of virtual machines running on Citrix XenServer host or pool
+short_description: Manages power states of virtual machines running on Citrix Hypervisor/XenServer host or pool
 description: >
    This module can be used to power on, power off, restart or suspend virtual machine and gracefully reboot or shutdown guest OS of virtual machine.
 version_added: '2.8'
@@ -22,9 +22,10 @@ author:
 - Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
 notes:
 - Minimal supported version of XenServer is 5.6.
-- Module was tested with XenServer 6.5, 7.1 and 7.2.
+- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
-- 'XenAPI Python library can be acquired from XenServer SDK (downloadable from Citrix website) or by running C(pip install XenAPI) (possibly very old
+- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside
-   version, not compatible with Python 3.x). Latest version can also be acquired from GitHub:
+   Citrix Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the XenAPI.py file from the SDK to your Python site-packages on your
+   Ansible Control Node to use it. Latest version of the library can also be acquired from GitHub:
    https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI.py'
 - 'If no scheme is specified in C(hostname), module defaults to C(http://) because C(https://) is problematic in most setups. Make sure you are
    accessing XenServer host in trusted environment or use C(https://) scheme explicitly.'

test/units/module_utils/xenserver/test_xenserverobject.py

@@ -20,9 +20,7 @@ def test_xenserverobject_xenapi_lib_detection(mocker, fake_ansible_module, xense
     with pytest.raises(FailJsonException) as exc_info:
         xenserver.XenServerObject(fake_ansible_module)
 
-    assert exc_info.value.kwargs['msg'] == ("XenAPI Python library is required for this module! "
+    assert 'Failed to import the required Python library (XenAPI) on' in exc_info.value.kwargs['msg']
-                                            "Please download XenServer SDK and copy XenAPI.py to your Python site-packages. "
-                                            "Check Notes section in module documentation for more info.")
 
 
 def test_xenserverobject_xenapi_failure(mock_xenapi_failure, fake_ansible_module, xenserver):