x*: adjust docs (#9308)

* adjust docs

* Update plugins/modules/xml.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* fix capitalisation

* add markup to references of the xe command (xenserver)

* add missing markup

* Update plugins/modules/xml.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Alexei Znamensky 2024-12-24 06:58:02 +13:00 committed by GitHub
commit f9bfe4e4a6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 827 additions and 863 deletions

View file

@ -8,27 +8,25 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: xenserver_guest_powerstate
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.
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.
author:
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
- Bojan Vitnik (@bvitnik) <bvitnik@mainstream.rs>
notes:
- Minimal supported version of XenServer is 5.6.
- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside
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:
U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/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.'
- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs: no)
which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
- Minimal supported version of XenServer is 5.6.
- Module was tested with XenServer 6.5, 7.1, 7.2, 7.6, Citrix Hypervisor 8.0, XCP-ng 7.6 and 8.0.
- 'To acquire XenAPI Python library, just run C(pip install XenAPI) on your Ansible Control Node. The library can also be found inside Citrix
Hypervisor/XenServer SDK (downloadable from Citrix website). Copy the C(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:
U(https://raw.githubusercontent.com/xapi-project/xen-api/master/scripts/examples/python/XenAPI/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.'
- 'To use C(https://) scheme for C(hostname) you have to either import host certificate to your OS certificate store or use C(validate_certs:
no) which requires XenAPI library from XenServer 7.2 SDK or newer and Python 2.7.9 or newer.'
requirements:
- XenAPI
- XenAPI
attributes:
check_mode:
support: full
@ -37,45 +35,44 @@ attributes:
options:
state:
description:
- Specify the state VM should be in.
- If O(state) is set to value other than V(present), then VM is transitioned into required state and facts are returned.
- If O(state) is set to V(present), then VM is just checked for existence and facts are returned.
- Specify the state VM should be in.
- If O(state) is set to value other than V(present), then VM is transitioned into required state and facts are returned.
- If O(state) is set to V(present), then VM is just checked for existence and facts are returned.
type: str
default: present
choices: [ powered-on, powered-off, restarted, shutdown-guest, reboot-guest, suspended, present ]
choices: [powered-on, powered-off, restarted, shutdown-guest, reboot-guest, suspended, present]
name:
description:
- Name of the VM to manage.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
- Name of the VM to manage.
- VMs running on XenServer do not necessarily have unique names. The module will fail if multiple VMs with same name are found.
- In case of multiple VMs with same name, use O(uuid) to uniquely specify VM to manage.
- This parameter is case sensitive.
type: str
aliases: [ name_label ]
aliases: [name_label]
uuid:
description:
- UUID of the VM to manage if known. This is XenServer's unique identifier.
- It is required if name is not unique.
- UUID of the VM to manage if known. This is XenServer's unique identifier.
- It is required if name is not unique.
type: str
wait_for_ip_address:
description:
- Wait until XenServer detects an IP address for the VM.
- This requires XenServer Tools to be preinstalled on the VM to work properly.
- Wait until XenServer detects an IP address for the VM.
- This requires XenServer Tools to be preinstalled on the VM to work properly.
type: bool
default: false
state_change_timeout:
description:
- 'By default, module will wait indefinitely for VM to change state or acquire an IP address if O(wait_for_ip_address=true).'
- If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
- In case of timeout, module will generate an error message.
- 'By default, module will wait indefinitely for VM to change state or acquire an IP address if O(wait_for_ip_address=true).'
- If this parameter is set to positive value, the module will instead wait specified number of seconds for the state change.
- In case of timeout, module will generate an error message.
type: int
default: 0
extends_documentation_fragment:
- community.general.xenserver.documentation
- community.general.attributes
- community.general.xenserver.documentation
- community.general.attributes
"""
'''
EXAMPLES = r'''
EXAMPLES = r"""
- name: Power on VM
community.general.xenserver_guest_powerstate:
hostname: "{{ xenserver_hostname }}"
@ -85,11 +82,11 @@ EXAMPLES = r'''
state: powered-on
delegate_to: localhost
register: facts
'''
"""
RETURN = r'''
RETURN = r"""
instance:
description: Metadata about the VM
description: Metadata about the VM.
returned: always
type: dict
sample: {
@ -174,7 +171,7 @@ instance:
"vm-data": ""
}
}
'''
"""
from ansible.module_utils.basic import AnsibleModule