From 29e9afcbf47fd6af38e9138836f89666a2184d61 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 14:01:25 +0100 Subject: [PATCH] [PR #9389/a9fca563 backport][stable-10] ma*.py: normalize docs (#9405) ma*.py: normalize docs (#9389) * ma*.py: normalize docs * Update plugins/modules/matrix.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit a9fca563746c361f7fcb558c257412a9793f7714) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/macports.py | 88 +++--- plugins/modules/mail.py | 111 ++++---- plugins/modules/make.py | 13 +- plugins/modules/manageiq_alert_profiles.py | 32 +-- plugins/modules/manageiq_alerts.py | 59 ++-- plugins/modules/manageiq_group.py | 102 ++++--- plugins/modules/manageiq_policies.py | 27 +- plugins/modules/manageiq_policies_info.py | 19 +- plugins/modules/manageiq_provider.py | 94 +++---- plugins/modules/manageiq_tags.py | 51 ++-- plugins/modules/manageiq_tags_info.py | 19 +- plugins/modules/manageiq_tenant.py | 70 ++--- plugins/modules/manageiq_user.py | 32 +-- plugins/modules/mas.py | 80 +++--- plugins/modules/matrix.py | 91 +++--- plugins/modules/mattermost.py | 39 ++- plugins/modules/maven_artifact.py | 308 ++++++++++----------- 17 files changed, 596 insertions(+), 639 deletions(-) diff --git a/plugins/modules/macports.py b/plugins/modules/macports.py index cd620687d7..3777b86c2f 100644 --- a/plugins/modules/macports.py +++ b/plugins/modules/macports.py @@ -12,54 +12,54 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: macports author: "Jimmy Tang (@jcftang)" short_description: Package manager for MacPorts description: - - Manages MacPorts packages (ports) + - Manages MacPorts packages (ports). extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - A list of port names. - aliases: ['port'] - type: list - elements: str - selfupdate: - description: - - Update Macports and the ports tree, either prior to installing ports or as a separate step. - - Equivalent to running C(port selfupdate). - aliases: ['update_cache', 'update_ports'] - default: false - type: bool - state: - description: - - Indicates the desired state of the port. - choices: [ 'present', 'absent', 'active', 'inactive', 'installed', 'removed'] - default: present - type: str - upgrade: - description: - - Upgrade all outdated ports, either prior to installing ports or as a separate step. - - Equivalent to running C(port upgrade outdated). - default: false - type: bool - variant: - description: - - A port variant specification. - - 'O(variant) is only supported with O(state=installed) and O(state=present).' - aliases: ['variants'] - type: str -''' -EXAMPLES = ''' + name: + description: + - A list of port names. + aliases: ['port'] + type: list + elements: str + selfupdate: + description: + - Update Macports and the ports tree, either prior to installing ports or as a separate step. + - Equivalent to running C(port selfupdate). + aliases: ['update_cache', 'update_ports'] + default: false + type: bool + state: + description: + - Indicates the desired state of the port. + choices: ['present', 'absent', 'active', 'inactive', 'installed', 'removed'] + default: present + type: str + upgrade: + description: + - Upgrade all outdated ports, either prior to installing ports or as a separate step. + - Equivalent to running C(port upgrade outdated). + default: false + type: bool + variant: + description: + - A port variant specification. + - O(variant) is only supported with O(state=installed) and O(state=present). + aliases: ['variants'] + type: str +""" + +EXAMPLES = r""" - name: Install the foo port community.general.macports: name: foo @@ -74,8 +74,8 @@ EXAMPLES = ''' name: "{{ ports }}" vars: ports: - - foo - - foo-tools + - foo + - foo-tools - name: Update Macports and the ports tree, then upgrade all outdated ports community.general.macports: @@ -101,7 +101,7 @@ EXAMPLES = ''' community.general.macports: name: foo state: inactive -''' +""" import re diff --git a/plugins/modules/mail.py b/plugins/modules/mail.py index 1916c140c3..0cca8646ca 100644 --- a/plugins/modules/mail.py +++ b/plugins/modules/mail.py @@ -9,27 +9,21 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: -- Dag Wieers (@dagwieers) + - Dag Wieers (@dagwieers) module: mail short_description: Send an email description: -- This module is useful for sending emails from playbooks. -- One may wonder why automate sending emails? In complex environments - there are from time to time processes that cannot be automated, either - because you lack the authority to make it so, or because not everyone - agrees to a common approach. -- If you cannot automate a specific step, but the step is non-blocking, - sending out an email to the responsible party to make them perform their - part of the bargain is an elegant way to put the responsibility in - someone else's lap. -- Of course sending out a mail can be equally useful as a way to notify - one or more people in a team that a specific action has been - (successfully) taken. + - This module is useful for sending emails from playbooks. + - One may wonder why automate sending emails? In complex environments there are from time to time processes that cannot be automated, either + because you lack the authority to make it so, or because not everyone agrees to a common approach. + - If you cannot automate a specific step, but the step is non-blocking, sending out an email to the responsible party to make them perform their + part of the bargain is an elegant way to put the responsibility in someone else's lap. + - Of course sending out a mail can be equally useful as a way to notify one or more people in a team that a specific action has been (successfully) + taken. extends_documentation_fragment: -- community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -38,106 +32,105 @@ attributes: options: sender: description: - - The email-address the mail is sent from. May contain address and phrase. + - The email-address the mail is sent from. May contain address and phrase. type: str default: root - aliases: [ from ] + aliases: [from] to: description: - - The email-address(es) the mail is being sent to. - - This is a list, which may contain address and phrase portions. + - The email-address(es) the mail is being sent to. + - This is a list, which may contain address and phrase portions. type: list elements: str default: root - aliases: [ recipients ] + aliases: [recipients] cc: description: - - The email-address(es) the mail is being copied to. - - This is a list, which may contain address and phrase portions. + - The email-address(es) the mail is being copied to. + - This is a list, which may contain address and phrase portions. type: list elements: str default: [] bcc: description: - - The email-address(es) the mail is being 'blind' copied to. - - This is a list, which may contain address and phrase portions. + - The email-address(es) the mail is being 'blind' copied to. + - This is a list, which may contain address and phrase portions. type: list elements: str default: [] subject: description: - - The subject of the email being sent. + - The subject of the email being sent. required: true type: str - aliases: [ msg ] + aliases: [msg] body: description: - - The body of the email being sent. + - The body of the email being sent. type: str username: description: - - If SMTP requires username. + - If SMTP requires username. type: str password: description: - - If SMTP requires password. + - If SMTP requires password. type: str host: description: - - The mail server. + - The mail server. type: str default: localhost port: description: - - The mail server port. - - This must be a valid integer between 1 and 65534 + - The mail server port. + - This must be a valid integer between V(1) and V(65534). type: int default: 25 attach: description: - - A list of pathnames of files to attach to the message. - - Attached files will have their content-type set to C(application/octet-stream). + - A list of pathnames of files to attach to the message. + - Attached files will have their content-type set to C(application/octet-stream). type: list elements: path default: [] headers: description: - - A list of headers which should be added to the message. - - Each individual header is specified as C(header=value) (see example below). + - A list of headers which should be added to the message. + - Each individual header is specified as V(header=value) (see example below). type: list elements: str default: [] charset: description: - - The character set of email being sent. + - The character set of email being sent. type: str default: utf-8 subtype: description: - - The minor mime type, can be either V(plain) or V(html). - - The major type is always V(text). + - The minor mime type, can be either V(plain) or V(html). + - The major type is always V(text). type: str - choices: [ html, plain ] + choices: [html, plain] default: plain secure: description: - - If V(always), the connection will only send email if the connection is Encrypted. - If the server doesn't accept the encrypted connection it will fail. - - If V(try), the connection will attempt to setup a secure SSL/TLS session, before trying to send. - - If V(never), the connection will not attempt to setup a secure SSL/TLS session, before sending - - If V(starttls), the connection will try to upgrade to a secure SSL/TLS connection, before sending. - If it is unable to do so it will fail. + - If V(always), the connection will only send email if the connection is Encrypted. If the server does not accept the encrypted connection + it will fail. + - If V(try), the connection will attempt to setup a secure SSL/TLS session, before trying to send. + - If V(never), the connection will not attempt to setup a secure SSL/TLS session, before sending. + - If V(starttls), the connection will try to upgrade to a secure SSL/TLS connection, before sending. If it is unable to do so it will fail. type: str - choices: [ always, never, starttls, try ] + choices: [always, never, starttls, try] default: try timeout: description: - - Sets the timeout in seconds for connection attempts. + - Sets the timeout in seconds for connection attempts. type: int default: 20 ehlohost: description: - - Allows for manual specification of host for EHLO. + - Allows for manual specification of host for EHLO. type: str version_added: 3.8.0 message_id_domain: @@ -147,9 +140,9 @@ options: type: str default: ansible version_added: 8.2.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Example playbook sending mail to root community.general.mail: subject: System {{ ansible_hostname }} has been successfully provisioned. @@ -174,15 +167,15 @@ EXAMPLES = r''' body: Hello, this is an e-mail. I hope you like it ;-) from: jane@example.net (Jane Jolie) to: - - John Doe - - Suzie Something + - John Doe + - Suzie Something cc: Charlie Root attach: - - /etc/group - - /tmp/avatar2.png + - /etc/group + - /tmp/avatar2.png headers: - - Reply-To=john@example.com - - X-Special="Something or other" + - Reply-To=john@example.com + - X-Special="Something or other" charset: us-ascii delegate_to: localhost @@ -222,7 +215,7 @@ EXAMPLES = r''' subject: Ansible-report body: System {{ ansible_hostname }} has been successfully provisioned. secure: starttls -''' +""" import os import smtplib diff --git a/plugins/modules/make.py b/plugins/modules/make.py index 39392afca6..a574560f7f 100644 --- a/plugins/modules/make.py +++ b/plugins/modules/make.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: make short_description: Run targets in a Makefile requirements: @@ -65,9 +64,9 @@ options: type: list elements: str version_added: 7.2.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Build the default target community.general.make: chdir: /home/ubuntu/cool-project @@ -103,9 +102,9 @@ EXAMPLES = r''' # The following adds TARGET=arm64 TARGET_ARCH=aarch64 to the command line: TARGET: arm64 TARGET_ARCH: aarch64 -''' +""" -RETURN = r''' +RETURN = r""" chdir: description: - The value of the module parameter O(chdir). @@ -143,7 +142,7 @@ targets: type: str returned: success version_added: 7.2.0 -''' +""" from ansible.module_utils.six import iteritems from ansible.module_utils.six.moves import shlex_quote diff --git a/plugins/modules/manageiq_alert_profiles.py b/plugins/modules/manageiq_alert_profiles.py index eb6424bcdd..33ca05df3b 100644 --- a/plugins/modules/manageiq_alert_profiles.py +++ b/plugins/modules/manageiq_alert_profiles.py @@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_alert_profiles short_description: Configuration of alert profiles for ManageIQ @@ -20,7 +19,6 @@ extends_documentation_fragment: author: Elad Alfassa (@elad661) description: - The manageiq_alert_profiles module supports adding, updating and deleting alert profiles in ManageIQ. - attributes: check_mode: support: none @@ -31,8 +29,8 @@ options: state: type: str description: - - absent - alert profile should not exist, - - present - alert profile should exist, + - V(absent) - alert profile should not exist, + - V(present) - alert profile should exist. choices: ['absent', 'present'] default: 'present' name: @@ -43,23 +41,21 @@ options: resource_type: type: str description: - - The resource type for the alert profile in ManageIQ. Required when state is "present". - choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster', - 'ExtManagementSystem', 'MiddlewareServer'] + - The resource type for the alert profile in ManageIQ. Required when O(state=present). + choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster', 'ExtManagementSystem', 'MiddlewareServer'] alerts: type: list elements: str description: - List of alert descriptions to assign to this profile. - - Required if state is "present" + - Required if O(state=present). notes: type: str description: - - Optional notes for this profile + - Optional notes for this profile. +""" -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Add an alert profile to ManageIQ community.general.manageiq_alert_profiles: state: present @@ -72,7 +68,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Delete an alert profile from ManageIQ community.general.manageiq_alert_profiles: @@ -82,11 +78,11 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! -''' + validate_certs: false # only do this when you trust the network! +""" -RETURN = ''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec diff --git a/plugins/modules/manageiq_alerts.py b/plugins/modules/manageiq_alerts.py index 53f40fb00c..9dd50af846 100644 --- a/plugins/modules/manageiq_alerts.py +++ b/plugins/modules/manageiq_alerts.py @@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_alerts short_description: Configuration of alerts in ManageIQ @@ -20,7 +19,6 @@ extends_documentation_fragment: author: Elad Alfassa (@elad661) description: - The manageiq_alerts module supports adding, updating and deleting alerts in ManageIQ. - attributes: check_mode: support: none @@ -31,8 +29,8 @@ options: state: type: str description: - - absent - alert should not exist, - - present - alert should exist, + - V(absent) - alert should not exist, + - V(present) - alert should exist. required: false choices: ['absent', 'present'] default: 'present' @@ -44,9 +42,8 @@ options: resource_type: type: str description: - - The entity type for the alert in ManageIQ. Required when state is "present". - choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster', - 'ExtManagementSystem', 'MiddlewareServer'] + - The entity type for the alert in ManageIQ. Required when O(state=present). + choices: ['Vm', 'ContainerNode', 'MiqServer', 'Host', 'Storage', 'EmsCluster', 'ExtManagementSystem', 'MiddlewareServer'] expression_type: type: str description: @@ -58,20 +55,18 @@ options: description: - The alert expression for ManageIQ. - Can either be in the "Miq Expression" format or the "Hash Expression format". - - Required if state is "present". + - Required if O(state=present). enabled: description: - - Enable or disable the alert. Required if state is "present". + - Enable or disable the alert. Required if O(state=present). type: bool options: type: dict description: - - Additional alert options, such as notification type and frequency + - Additional alert options, such as notification type and frequency. +""" - -''' - -EXAMPLES = ''' +EXAMPLES = r""" - name: Add an alert with a "hash expression" to ManageIQ community.general.manageiq_alerts: state: present @@ -83,15 +78,15 @@ EXAMPLES = ''' from: "example@example.com" resource_type: ContainerNode expression: - eval_method: hostd_log_threshold - mode: internal - options: {} + eval_method: hostd_log_threshold + mode: internal + options: {} enabled: true manageiq_connection: url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Add an alert with a "miq expression" to ManageIQ community.general.manageiq_alerts: @@ -105,20 +100,20 @@ EXAMPLES = ''' resource_type: Vm expression_type: miq expression: - and: - - CONTAINS: - tag: Vm.managed-environment - value: prod - - not: - CONTAINS: - tag: Vm.host.managed-environment - value: prod + and: + - CONTAINS: + tag: Vm.managed-environment + value: prod + - not: + CONTAINS: + tag: Vm.host.managed-environment + value: prod enabled: true manageiq_connection: url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Delete an alert from ManageIQ community.general.manageiq_alerts: @@ -128,11 +123,11 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! -''' + validate_certs: false # only do this when you trust the network! +""" -RETURN = ''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec diff --git a/plugins/modules/manageiq_group.py b/plugins/modules/manageiq_group.py index e060b9a01a..9858dd5947 100644 --- a/plugins/modules/manageiq_group.py +++ b/plugins/modules/manageiq_group.py @@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_group short_description: Management of groups in ManageIQ @@ -33,70 +32,69 @@ options: state: type: str description: - - absent - group should not exist, present - group should be. + - V(absent) - group should not exist, + - V(present) - group should exist. choices: ['absent', 'present'] default: 'present' description: type: str description: - - The group description. + - The group description. required: true - default: null role_id: type: int description: - - The the group role id + - The the group role id. required: false - default: null role: type: str description: - - The the group role name - - The O(role_id) has precedence over the O(role) when supplied. + - The the group role name. + - The O(role_id) has precedence over the O(role) when supplied. required: false - default: null + default: tenant_id: type: int description: - - The tenant for the group identified by the tenant id. + - The tenant for the group identified by the tenant id. required: false - default: null + default: tenant: type: str description: - - The tenant for the group identified by the tenant name. - - The O(tenant_id) has precedence over the O(tenant) when supplied. - - Tenant names are case sensitive. + - The tenant for the group identified by the tenant name. + - The O(tenant_id) has precedence over the O(tenant) when supplied. + - Tenant names are case sensitive. required: false - default: null + default: managed_filters: - description: The tag values per category + description: The tag values per category. type: dict required: false - default: null + default: managed_filters_merge_mode: type: str description: - - In merge mode existing categories are kept or updated, new categories are added. - - In replace mode all categories will be replaced with the supplied O(managed_filters). - choices: [ merge, replace ] + - In merge mode existing categories are kept or updated, new categories are added. + - In replace mode all categories will be replaced with the supplied O(managed_filters). + choices: [merge, replace] default: replace belongsto_filters: - description: A list of strings with a reference to the allowed host, cluster or folder + description: A list of strings with a reference to the allowed host, cluster or folder. type: list elements: str required: false - default: null + default: belongsto_filters_merge_mode: type: str description: - - In merge mode existing settings are merged with the supplied O(belongsto_filters). - - In replace mode current values are replaced with the supplied O(belongsto_filters). - choices: [ merge, replace ] + - In merge mode existing settings are merged with the supplied O(belongsto_filters). + - In replace mode current values are replaced with the supplied O(belongsto_filters). + choices: [merge, replace] default: replace -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a group in ManageIQ with the role EvmRole-user and tenant 'my_tenant' community.general.manageiq_group: description: 'MyGroup-user' @@ -106,7 +104,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Create a group in ManageIQ with the role EvmRole-user and tenant with tenant_id 4 community.general.manageiq_group: @@ -117,33 +115,33 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: - - Create or update a group in ManageIQ with the role EvmRole-user and tenant my_tenant. - - Apply 3 prov_max_cpu and 2 department tags to the group. - - Limit access to a cluster for the group. + - Create or update a group in ManageIQ with the role EvmRole-user and tenant my_tenant. + - Apply 3 prov_max_cpu and 2 department tags to the group. + - Limit access to a cluster for the group. community.general.manageiq_group: description: 'MyGroup-user' role: 'EvmRole-user' tenant: my_tenant managed_filters: prov_max_cpu: - - '1' - - '2' - - '4' + - '1' + - '2' + - '4' department: - - defense - - engineering + - defense + - engineering managed_filters_merge_mode: replace belongsto_filters: - - "/belongsto/ExtManagementSystem|ProviderName/EmsFolder|Datacenters/EmsFolder|dc_name/EmsFolder|host/EmsCluster|Cluster name" + - "/belongsto/ExtManagementSystem|ProviderName/EmsFolder|Datacenters/EmsFolder|dc_name/EmsFolder|host/EmsCluster|Cluster name" belongsto_filters_merge_mode: merge manageiq_connection: url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Delete a group in ManageIQ community.general.manageiq_group: @@ -161,53 +159,53 @@ EXAMPLES = ''' manageiq_connection: url: 'http://127.0.0.1:3000' token: 'sometoken' -''' +""" -RETURN = ''' +RETURN = r""" group: description: The group. returned: success type: complex contains: description: - description: The group description + description: The group description. returned: success type: str id: - description: The group id + description: The group id. returned: success type: int group_type: - description: The group type, system or user + description: The group type, system or user. returned: success type: str role: - description: The group role name + description: The group role name. returned: success type: str tenant: - description: The group tenant name + description: The group tenant name. returned: success type: str managed_filters: - description: The tag values per category + description: The tag values per category. returned: success type: dict belongsto_filters: - description: A list of strings with a reference to the allowed host, cluster or folder + description: A list of strings with a reference to the allowed host, cluster or folder. returned: success type: list created_on: - description: Group creation date + description: Group creation date. returned: success type: str sample: "2018-08-12T08:37:55+00:00" updated_on: - description: Group update date + description: Group update date. returned: success type: int sample: "2018-08-12T08:37:55+00:00" -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec diff --git a/plugins/modules/manageiq_policies.py b/plugins/modules/manageiq_policies.py index f2101ad28b..e53388f293 100644 --- a/plugins/modules/manageiq_policies.py +++ b/plugins/modules/manageiq_policies.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_policies short_description: Management of resource policy_profiles in ManageIQ @@ -21,7 +20,6 @@ extends_documentation_fragment: author: Daniel Korn (@dkorn) description: - The manageiq_policies module supports adding and deleting policy_profiles in ManageIQ. - attributes: check_mode: support: none @@ -33,7 +31,7 @@ options: type: str description: - V(absent) - policy_profiles should not exist, - - V(present) - policy_profiles should exist, + - V(present) - policy_profiles should exist. choices: ['absent', 'present'] default: 'present' policy_profiles: @@ -47,9 +45,8 @@ options: description: - The type of the resource to which the profile should be [un]assigned. required: true - choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', - 'data store', 'group', 'resource pool', 'service', 'service template', - 'template', 'tenant', 'user'] + choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template', + 'template', 'tenant', 'user'] resource_name: type: str description: @@ -61,9 +58,9 @@ options: - The ID of the resource to which the profile should be [un]assigned. - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. version_added: 2.2.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Assign new policy_profile for a provider in ManageIQ community.general.manageiq_policies: resource_name: 'EngLab' @@ -74,7 +71,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Unassign a policy_profile for a provider in ManageIQ community.general.manageiq_policies: @@ -87,13 +84,13 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! -''' + validate_certs: false # only do this when you trust the network! +""" -RETURN = ''' +RETURN = r""" manageiq_policies: description: - - List current policy_profile and policies for a provider in ManageIQ + - List current policy_profile and policies for a provider in ManageIQ. returned: always type: dict sample: '{ @@ -122,7 +119,7 @@ manageiq_policies: } ] }' -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec, manageiq_entities diff --git a/plugins/modules/manageiq_policies_info.py b/plugins/modules/manageiq_policies_info.py index fda7dcadfe..f4235203ab 100644 --- a/plugins/modules/manageiq_policies_info.py +++ b/plugins/modules/manageiq_policies_info.py @@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_policies_info version_added: 5.8.0 @@ -24,16 +23,14 @@ extends_documentation_fragment: author: Alexei Znamensky (@russoz) description: - The manageiq_policies module supports listing policy_profiles in ManageIQ. - options: resource_type: type: str description: - The type of the resource to obtain the profile for. required: true - choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', - 'data store', 'group', 'resource pool', 'service', 'service template', - 'template', 'tenant', 'user'] + choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template', + 'template', 'tenant', 'user'] resource_name: type: str description: @@ -44,9 +41,9 @@ options: description: - The ID of the resource to obtain the profile for. - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List current policy_profile and policies for a provider in ManageIQ community.general.manageiq_policies_info: resource_name: 'EngLab' @@ -56,9 +53,9 @@ EXAMPLES = ''' username: 'admin' password: 'smartvm' register: result -''' +""" -RETURN = ''' +RETURN = r""" profiles: description: - List current policy_profile and policies for a provider in ManageIQ. @@ -78,7 +75,7 @@ profiles: name: schedule compliance after smart state analysis profile_description: OpenSCAP profile profile_name: openscap profile -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec, manageiq_entities diff --git a/plugins/modules/manageiq_provider.py b/plugins/modules/manageiq_provider.py index 35c73a38b3..98677c7beb 100644 --- a/plugins/modules/manageiq_provider.py +++ b/plugins/modules/manageiq_provider.py @@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: manageiq_provider short_description: Management of provider in ManageIQ extends_documentation_fragment: @@ -19,7 +19,6 @@ extends_documentation_fragment: author: Daniel Korn (@dkorn) description: - The manageiq_provider module supports adding, updating, and deleting provider in ManageIQ. - attributes: check_mode: support: none @@ -30,7 +29,9 @@ options: state: type: str description: - - absent - provider should not exist, present - provider should be present, refresh - provider will be refreshed + - V(absent) - provider should not exist, + - V(present) - provider should be present, + - V(refresh) - provider will be refreshed. choices: ['absent', 'present', 'refresh'] default: 'present' name: @@ -47,30 +48,30 @@ options: default: 'default' provider_region: type: str - description: The provider region name to connect to (e.g. AWS region for Amazon). + description: The provider region name to connect to (for example AWS region for Amazon). host_default_vnc_port_start: type: str - description: The first port in the host VNC range. defaults to None. + description: The first port in the host VNC range. host_default_vnc_port_end: type: str - description: The last port in the host VNC range. defaults to None. + description: The last port in the host VNC range. subscription: type: str - description: Microsoft Azure subscription ID. defaults to None. + description: Microsoft Azure subscription ID. project: type: str - description: Google Compute Engine Project ID. defaults to None. + description: Google Compute Engine Project ID. azure_tenant_id: type: str description: Tenant ID. defaults to None. - aliases: [ keystone_v3_domain_id ] + aliases: [keystone_v3_domain_id] tenant_mapping_enabled: type: bool default: false - description: Whether to enable mapping of existing tenants. defaults to False. + description: Whether to enable mapping of existing tenants. api_version: type: str - description: The OpenStack Keystone API version. defaults to None. + description: The OpenStack Keystone API version. choices: ['v2', 'v3'] provider: @@ -79,32 +80,32 @@ options: suboptions: hostname: type: str - description: The provider's api hostname. + description: The provider's API hostname. required: true port: type: int - description: The provider's api port. + description: The provider's API port. userid: type: str - description: Provider's api endpoint authentication userid. defaults to None. + description: Provider's API endpoint authentication userid. password: type: str - description: Provider's api endpoint authentication password. defaults to None. + description: Provider's API endpoint authentication password. auth_key: type: str - description: Provider's api endpoint authentication bearer token. defaults to None. + description: Provider's API endpoint authentication bearer token. validate_certs: - description: Whether SSL certificates should be verified for HTTPS requests (deprecated). defaults to True. + description: Whether SSL certificates should be verified for HTTPS requests (deprecated). type: bool default: true - aliases: [ verify_ssl ] + aliases: [verify_ssl] security_protocol: type: str - description: How SSL certificates should be used for HTTPS requests. defaults to None. - choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation','non-ssl'] + description: How SSL certificates should be used for HTTPS requests. + choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl'] certificate_authority: type: str - description: The CA bundle string with custom certificates. defaults to None. + description: The CA bundle string with custom certificates. path: type: str description: @@ -125,39 +126,38 @@ options: type: str description: - TODO needs documentation. - metrics: description: Metrics endpoint connection information. type: dict suboptions: hostname: type: str - description: The provider's api hostname. + description: The provider's API hostname. required: true port: type: int - description: The provider's api port. + description: The provider's API port. userid: type: str - description: Provider's api endpoint authentication userid. defaults to None. + description: Provider's API endpoint authentication userid. password: type: str - description: Provider's api endpoint authentication password. defaults to None. + description: Provider's API endpoint authentication password. auth_key: type: str - description: Provider's api endpoint authentication bearer token. defaults to None. + description: Provider's API endpoint authentication bearer token. validate_certs: - description: Whether SSL certificates should be verified for HTTPS requests (deprecated). defaults to True. + description: Whether SSL certificates should be verified for HTTPS requests (deprecated). type: bool default: true - aliases: [ verify_ssl ] + aliases: [verify_ssl] security_protocol: type: str - choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation','non-ssl'] - description: How SSL certificates should be used for HTTPS requests. defaults to None. + choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl'] + description: How SSL certificates should be used for HTTPS requests. certificate_authority: type: str - description: The CA bundle string with custom certificates. defaults to None. + description: The CA bundle string with custom certificates. path: type: str description: Database name for oVirt metrics. Defaults to V(ovirt_engine_history). @@ -177,35 +177,34 @@ options: type: str description: - TODO needs documentation. - alerts: description: Alerts endpoint connection information. type: dict suboptions: hostname: type: str - description: The provider's api hostname. + description: The provider's API hostname. required: true port: type: int - description: The provider's api port. + description: The provider's API port. userid: type: str - description: Provider's api endpoint authentication userid. defaults to None. + description: Provider's API endpoint authentication userid. defaults to None. password: type: str - description: Provider's api endpoint authentication password. defaults to None. + description: Provider's API endpoint authentication password. defaults to None. auth_key: type: str - description: Provider's api endpoint authentication bearer token. defaults to None. + description: Provider's API endpoint authentication bearer token. defaults to None. validate_certs: type: bool description: Whether SSL certificates should be verified for HTTPS requests (deprecated). defaults to True. default: true - aliases: [ verify_ssl ] + aliases: [verify_ssl] security_protocol: type: str - choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation', 'non-ssl'] + choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl'] description: How SSL certificates should be used for HTTPS requests. defaults to None. certificate_authority: type: str @@ -230,7 +229,6 @@ options: type: str description: - TODO needs documentation. - ssh_keypair: description: SSH key pair used for SSH connections to all hosts in this provider. type: dict @@ -250,10 +248,10 @@ options: - Whether certificates should be verified for connections. type: bool default: true - aliases: [ verify_ssl ] + aliases: [verify_ssl] security_protocol: type: str - choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation', 'non-ssl'] + choices: ['ssl-with-validation', 'ssl-with-validation-custom-ca', 'ssl-without-validation', 'non-ssl'] description: - TODO needs documentation. certificate_authority: @@ -288,9 +286,9 @@ options: type: int description: - TODO needs documentation. -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a new provider in ManageIQ ('Hawkular' metrics) community.general.manageiq_provider: name: 'EngLab' @@ -507,10 +505,10 @@ EXAMPLES = ''' hostname: 'gce.example.com' auth_key: 'google_json_key' validate_certs: 'false' -''' +""" -RETURN = ''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec diff --git a/plugins/modules/manageiq_tags.py b/plugins/modules/manageiq_tags.py index 3ab5eca4f8..bae59353cf 100644 --- a/plugins/modules/manageiq_tags.py +++ b/plugins/modules/manageiq_tags.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_tags short_description: Management of resource tags in ManageIQ @@ -21,7 +20,6 @@ extends_documentation_fragment: author: Daniel Korn (@dkorn) description: - The manageiq_tags module supports adding, updating and deleting tags in ManageIQ. - attributes: check_mode: support: none @@ -32,7 +30,7 @@ options: state: type: str description: - - V(absent) - tags should not exist. + - V(absent) - tags should not exist, - V(present) - tags should exist. choices: ['absent', 'present'] default: 'present' @@ -47,9 +45,8 @@ options: description: - The relevant resource type in manageiq. required: true - choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', - 'data store', 'group', 'resource pool', 'service', 'service template', - 'template', 'tenant', 'user'] + choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template', + 'template', 'tenant', 'user'] resource_name: type: str description: @@ -61,38 +58,38 @@ options: - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. type: int version_added: 2.2.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create new tags for a provider in ManageIQ. community.general.manageiq_tags: resource_name: 'EngLab' resource_type: 'provider' tags: - - category: environment - name: prod - - category: owner - name: prod_ops + - category: environment + name: prod + - category: owner + name: prod_ops manageiq_connection: url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when connecting to localhost! + validate_certs: false # only do this when connecting to localhost! - name: Create new tags for a provider in ManageIQ. community.general.manageiq_tags: resource_id: 23000000790497 resource_type: 'provider' tags: - - category: environment - name: prod - - category: owner - name: prod_ops + - category: environment + name: prod + - category: owner + name: prod_ops manageiq_connection: url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when connecting to localhost! + validate_certs: false # only do this when connecting to localhost! - name: Remove tags for a provider in ManageIQ. community.general.manageiq_tags: @@ -100,19 +97,19 @@ EXAMPLES = ''' resource_name: 'EngLab' resource_type: 'provider' tags: - - category: environment - name: prod - - category: owner - name: prod_ops + - category: environment + name: prod + - category: owner + name: prod_ops manageiq_connection: url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when connecting to localhost! -''' + validate_certs: false # only do this when connecting to localhost! +""" -RETURN = ''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ( diff --git a/plugins/modules/manageiq_tags_info.py b/plugins/modules/manageiq_tags_info.py index 75e111540b..5d32104e7a 100644 --- a/plugins/modules/manageiq_tags_info.py +++ b/plugins/modules/manageiq_tags_info.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_tags_info version_added: 5.8.0 short_description: Retrieve resource tags in ManageIQ @@ -22,16 +21,14 @@ extends_documentation_fragment: author: Alexei Znamensky (@russoz) description: - This module supports retrieving resource tags from ManageIQ. - options: resource_type: type: str description: - The relevant resource type in ManageIQ. required: true - choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', - 'data store', 'group', 'resource pool', 'service', 'service template', - 'template', 'tenant', 'user'] + choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template', + 'template', 'tenant', 'user'] resource_name: type: str description: @@ -42,9 +39,9 @@ options: - The ID of the resource at which tags will be controlled. - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. type: int -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List current tags for a provider in ManageIQ. community.general.manageiq_tags_info: resource_name: 'EngLab' @@ -54,15 +51,15 @@ EXAMPLES = ''' username: 'admin' password: 'smartvm' register: result -''' +""" -RETURN = ''' +RETURN = r""" tags: description: List of tags associated with the resource. returned: on success type: list elements: dict -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ( diff --git a/plugins/modules/manageiq_tenant.py b/plugins/modules/manageiq_tenant.py index a5a56191e7..4700e46356 100644 --- a/plugins/modules/manageiq_tenant.py +++ b/plugins/modules/manageiq_tenant.py @@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_tenant short_description: Management of tenants in ManageIQ @@ -31,7 +30,8 @@ options: state: type: str description: - - absent - tenant should not exist, present - tenant should be. + - V(absent) - tenant should not exist, + - V(present) - tenant should be. choices: ['absent', 'present'] default: 'present' name: @@ -39,42 +39,42 @@ options: description: - The tenant name. required: true - default: null + default: description: type: str description: - - The tenant description. + - The tenant description. required: true - default: null + default: parent_id: type: int description: - - The id of the parent tenant. If not supplied the root tenant is used. - - The O(parent_id) takes president over O(parent) when supplied + - The id of the parent tenant. If not supplied the root tenant is used. + - The O(parent_id) takes president over O(parent) when supplied. required: false - default: null + default: parent: type: str description: - - The name of the parent tenant. If not supplied and no O(parent_id) is supplied the root tenant is used. + - The name of the parent tenant. If not supplied and no O(parent_id) is supplied the root tenant is used. required: false - default: null + default: quotas: type: dict description: - - The tenant quotas. - - All parameters case sensitive. - - 'Valid attributes are:' - - ' - C(cpu_allocated) (int): use null to remove the quota.' - - ' - C(mem_allocated) (GB): use null to remove the quota.' - - ' - C(storage_allocated) (GB): use null to remove the quota.' - - ' - C(vms_allocated) (int): use null to remove the quota.' - - ' - C(templates_allocated) (int): use null to remove the quota.' + - The tenant quotas. + - All parameters case sensitive. + - 'Valid attributes are:' + - '- V(cpu_allocated) (int): use null to remove the quota.' + - '- V(mem_allocated) (GB): use null to remove the quota.' + - '- V(storage_allocated) (GB): use null to remove the quota.' + - '- V(vms_allocated) (int): use null to remove the quota.' + - '- V(templates_allocated) (int): use null to remove the quota.' required: false default: {} -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Update the root tenant in ManageIQ community.general.manageiq_tenant: name: 'My Company' @@ -83,7 +83,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Create a tenant in ManageIQ community.general.manageiq_tenant: @@ -94,7 +94,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Delete a tenant in ManageIQ community.general.manageiq_tenant: @@ -105,7 +105,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Set tenant quota for cpu_allocated, mem_allocated, remove quota for vms_allocated community.general.manageiq_tenant: @@ -114,12 +114,12 @@ EXAMPLES = ''' quotas: - cpu_allocated: 100 - mem_allocated: 50 - - vms_allocated: null + - vms_allocated: manageiq_connection: url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Delete a tenant in ManageIQ using a token @@ -130,39 +130,39 @@ EXAMPLES = ''' manageiq_connection: url: 'http://127.0.0.1:3000' token: 'sometoken' - validate_certs: false # only do this when you trust the network! -''' + validate_certs: false # only do this when you trust the network! +""" -RETURN = ''' +RETURN = r""" tenant: description: The tenant. returned: success type: complex contains: id: - description: The tenant id + description: The tenant id. returned: success type: int name: - description: The tenant name + description: The tenant name. returned: success type: str description: - description: The tenant description + description: The tenant description. returned: success type: str parent_id: - description: The id of the parent tenant + description: The id of the parent tenant. returned: success type: int quotas: - description: List of tenant quotas + description: List of tenant quotas. returned: success type: list sample: cpu_allocated: 100 mem_allocated: 50 -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec diff --git a/plugins/modules/manageiq_user.py b/plugins/modules/manageiq_user.py index 0d8a81984f..a4d5c21dfc 100644 --- a/plugins/modules/manageiq_user.py +++ b/plugins/modules/manageiq_user.py @@ -8,8 +8,7 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: manageiq_user short_description: Management of users in ManageIQ @@ -20,7 +19,6 @@ extends_documentation_fragment: author: Daniel Korn (@dkorn) description: - The manageiq_user module supports adding, updating and deleting users in ManageIQ. - attributes: check_mode: support: none @@ -31,7 +29,8 @@ options: state: type: str description: - - absent - user should not exist, present - user should be. + - V(absent) - user should not exist, + - V(present) - user should be. choices: ['absent', 'present'] default: 'present' userid: @@ -60,10 +59,11 @@ options: default: always choices: ['always', 'on_create'] description: - - V(always) will update passwords unconditionally. V(on_create) will only set the password for a newly created user. -''' + - V(always) will update passwords unconditionally. + - V(on_create) will only set the password for a newly created user. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a new user in ManageIQ community.general.manageiq_user: userid: 'jdoe' @@ -75,7 +75,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Create a new user in ManageIQ using a token community.general.manageiq_user: @@ -87,7 +87,7 @@ EXAMPLES = ''' manageiq_connection: url: 'http://127.0.0.1:3000' token: 'sometoken' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Delete a user in ManageIQ community.general.manageiq_user: @@ -97,7 +97,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Delete a user in ManageIQ using a token community.general.manageiq_user: @@ -106,7 +106,7 @@ EXAMPLES = ''' manageiq_connection: url: 'http://127.0.0.1:3000' token: 'sometoken' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Update email of user in ManageIQ community.general.manageiq_user: @@ -116,7 +116,7 @@ EXAMPLES = ''' url: 'http://127.0.0.1:3000' username: 'admin' password: 'smartvm' - validate_certs: false # only do this when you trust the network! + validate_certs: false # only do this when you trust the network! - name: Update email of user in ManageIQ using a token community.general.manageiq_user: @@ -125,11 +125,11 @@ EXAMPLES = ''' manageiq_connection: url: 'http://127.0.0.1:3000' token: 'sometoken' - validate_certs: false # only do this when you trust the network! -''' + validate_certs: false # only do this when you trust the network! +""" -RETURN = ''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible_collections.community.general.plugins.module_utils.manageiq import ManageIQ, manageiq_argument_spec diff --git a/plugins/modules/mas.py b/plugins/modules/mas.py index 8bb80840ca..3659c97636 100644 --- a/plugins/modules/mas.py +++ b/plugins/modules/mas.py @@ -10,54 +10,54 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: mas short_description: Manage Mac App Store applications with mas-cli description: - - Installs, uninstalls and updates macOS applications from the Mac App Store using the C(mas-cli). + - Installs, uninstalls and updates macOS applications from the Mac App Store using the C(mas-cli). version_added: '0.2.0' author: - - Michael Heap (@mheap) - - Lukas Bestle (@lukasbestle) + - Michael Heap (@mheap) + - Lukas Bestle (@lukasbestle) extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - id: - description: - - The Mac App Store identifier of the app(s) you want to manage. - - This can be found by running C(mas search APP_NAME) on your machine. - type: list - elements: int - state: - description: - - Desired state of the app installation. - - The V(absent) value requires root permissions, also see the examples. - type: str - choices: - - absent - - latest - - present - default: present - upgrade_all: - description: - - Upgrade all installed Mac App Store apps. - type: bool - default: false - aliases: ["upgrade"] + id: + description: + - The Mac App Store identifier of the app(s) you want to manage. + - This can be found by running C(mas search APP_NAME) on your machine. + type: list + elements: int + state: + description: + - Desired state of the app installation. + - The V(absent) value requires root permissions, also see the examples. + type: str + choices: + - absent + - latest + - present + default: present + upgrade_all: + description: + - Upgrade all installed Mac App Store apps. + type: bool + default: false + aliases: ["upgrade"] requirements: - - macOS 10.11+ - - "mas-cli (U(https://github.com/mas-cli/mas)) 1.5.0+ available as C(mas) in the bin path" - - The Apple ID to use already needs to be signed in to the Mac App Store (check with C(mas account)). - - The feature of "checking if user is signed in" is disabled for anyone using macOS 12.0+. - - Users need to sign in via the Mac App Store GUI beforehand for anyone using macOS 12.0+ due to U(https://github.com/mas-cli/mas/issues/417). -''' + - macOS 10.11 or higher. + - "mas-cli (U(https://github.com/mas-cli/mas)) 1.5.0+ available as C(mas) in the bin path" + - The Apple ID to use already needs to be signed in to the Mac App Store (check with C(mas account)). + - The feature of "checking if user is signed in" is disabled for anyone using macOS 12.0+. + - Users need to sign in to the Mac App Store GUI beforehand for anyone using macOS 12.0+ due to U(https://github.com/mas-cli/mas/issues/417). +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install Keynote community.general.mas: id: 409183694 @@ -99,9 +99,9 @@ EXAMPLES = ''' id: 413857545 state: absent become: true # Uninstallation requires root permissions -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.basic import AnsibleModule import os diff --git a/plugins/modules/matrix.py b/plugins/modules/matrix.py index 0b419c8d93..8a9fcf175c 100644 --- a/plugins/modules/matrix.py +++ b/plugins/modules/matrix.py @@ -8,58 +8,57 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" author: "Jan Christian Grünhage (@jcgruenhage)" module: matrix short_description: Send notifications to matrix description: - - This module sends html formatted notifications to matrix rooms. + - This module sends html formatted notifications to matrix rooms. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - msg_plain: - type: str - description: - - Plain text form of the message to send to matrix, usually markdown - required: true - msg_html: - type: str - description: - - HTML form of the message to send to matrix - required: true - room_id: - type: str - description: - - ID of the room to send the notification to - required: true - hs_url: - type: str - description: - - URL of the homeserver, where the CS-API is reachable - required: true - token: - type: str - description: - - Authentication token for the API call. If provided, user_id and password are not required - user_id: - type: str - description: - - The user id of the user - password: - type: str - description: - - The password to log in with + msg_plain: + type: str + description: + - Plain text form of the message to send to matrix, usually markdown. + required: true + msg_html: + type: str + description: + - HTML form of the message to send to matrix. + required: true + room_id: + type: str + description: + - ID of the room to send the notification to. + required: true + hs_url: + type: str + description: + - URL of the homeserver, where the CS-API is reachable. + required: true + token: + type: str + description: + - Authentication token for the API call. If provided, O(user_id) and O(password) are not required. + user_id: + type: str + description: + - The user id of the user. + password: + type: str + description: + - The password to log in with. requirements: - - matrix-client (Python library) -''' + - matrix-client (Python library) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Send matrix notification with token community.general.matrix: msg_plain: "**hello world**" @@ -76,10 +75,10 @@ EXAMPLES = ''' hs_url: "https://matrix.org" user_id: "ansible_notification_bot" password: "{{ matrix_auth_password }}" -''' +""" -RETURN = ''' -''' +RETURN = r""" +""" import traceback from ansible.module_utils.basic import AnsibleModule, missing_required_lib diff --git a/plugins/modules/mattermost.py b/plugins/modules/mattermost.py index af8ce69600..4b39c64170 100644 --- a/plugins/modules/mattermost.py +++ b/plugins/modules/mattermost.py @@ -15,14 +15,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: mattermost short_description: Send Mattermost notifications description: - - Sends notifications to U(http://your.mattermost.url) via the Incoming WebHook integration. + - Sends notifications to U(http://your.mattermost.url) using the Incoming WebHook integration. author: "Benjamin Jolivot (@bjolivot)" extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -32,15 +32,13 @@ options: url: type: str description: - - Mattermost url (i.e. http://mattermost.yourcompany.com). + - Mattermost url (for example V(http://mattermost.yourcompany.com)). required: true api_key: type: str description: - - Mattermost webhook api key. Log into your mattermost site, go to - Menu -> Integration -> Incoming Webhook -> Add Incoming Webhook. - This will give you full URL. O(api_key) is the last part. - http://mattermost.example.com/hooks/C(API_KEY) + - Mattermost webhook api key. Log into your mattermost site, go to Menu -> Integration -> Incoming Webhook -> Add Incoming Webhook. This + will give you full URL. O(api_key) is the last part. U(http://mattermost.example.com/hooks/API_KEY). required: true text: type: str @@ -73,17 +71,16 @@ options: type: str description: - Set a priority for the message. - choices: [ important, urgent ] + choices: [important, urgent] version_added: 10.0.0 validate_certs: description: - - If V(false), SSL certificates will not be validated. This should only be used - on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. default: true type: bool -''' +""" -EXAMPLES = """ +EXAMPLES = r""" - name: Send notification message via Mattermost community.general.mattermost: url: http://mattermost.example.com @@ -117,16 +114,16 @@ EXAMPLES = """ short: true """ -RETURN = ''' +RETURN = r""" payload: - description: Mattermost payload - returned: success - type: str + description: Mattermost payload. + returned: success + type: str webhook_url: - description: URL the webhook is sent to - returned: success - type: str -''' + description: URL the webhook is sent to. + returned: success + type: str +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.urls import fetch_url diff --git a/plugins/modules/maven_artifact.py b/plugins/modules/maven_artifact.py index e239b4a164..7193626999 100644 --- a/plugins/modules/maven_artifact.py +++ b/plugins/modules/maven_artifact.py @@ -11,171 +11,165 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: maven_artifact short_description: Downloads an Artifact from a Maven Repository description: - - Downloads an artifact from a maven repository given the maven coordinates provided to the module. - - Can retrieve snapshots or release versions of the artifact and will resolve the latest available - version if one is not available. + - Downloads an artifact from a maven repository given the maven coordinates provided to the module. + - Can retrieve snapshots or release versions of the artifact and will resolve the latest available version if one is not available. author: "Chris Schmidt (@chrisisbeef)" requirements: - - lxml - - boto if using a S3 repository (V(s3://...)) + - lxml + - boto if using a S3 repository (V(s3://...)) attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - group_id: - type: str - description: - - The Maven groupId coordinate. - required: true - artifact_id: - type: str - description: - - The maven artifactId coordinate. - required: true - version: - type: str - description: - - The maven version coordinate. - - Mutually exclusive with O(version_by_spec). - version_by_spec: - type: str - description: - - The maven dependency version ranges. - - See supported version ranges on U(https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution) - - The range type V((,1.0],[1.2,\)) and V((,1.1\),(1.1,\)) is not supported. - - Mutually exclusive with O(version). - version_added: '0.2.0' - classifier: - type: str - description: - - The maven classifier coordinate. - default: '' - extension: - type: str - description: - - The maven type/extension coordinate. - default: jar - repository_url: - type: str - description: - - The URL of the Maven Repository to download from. - - Use V(s3://...) if the repository is hosted on Amazon S3. - - Use V(file://...) if the repository is local. - default: https://repo1.maven.org/maven2 - username: - type: str - description: - - The username to authenticate as to the Maven Repository. Use AWS secret key of the repository is hosted on S3. - aliases: [ "aws_secret_key" ] - password: - type: str - description: - - The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on S3. - aliases: [ "aws_secret_access_key" ] - headers: - description: - - Add custom HTTP headers to a request in hash/dict format. - type: dict - force_basic_auth: - description: - - httplib2, the library used by the uri module only sends authentication information when a webservice - responds to an initial request with a 401 status. Since some basic auth services do not properly - send a 401, logins will fail. This option forces the sending of the Basic authentication header - upon initial request. - default: false - type: bool - version_added: '0.2.0' - dest: - type: path - description: - - The path where the artifact should be written to. - - If file mode or ownerships are specified and destination path already exists, they affect the downloaded file. - required: true - state: - type: str - description: - - The desired state of the artifact. - default: present - choices: [present,absent] - timeout: - type: int - description: - - Specifies a timeout in seconds for the connection attempt. - default: 10 - validate_certs: - description: - - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists. - type: bool - default: true - client_cert: - description: - - PEM formatted certificate chain file to be used for SSL client authentication. - - This file can also include the key as well, and if the key is included, O(client_key) is not required. - type: path - version_added: '1.3.0' - client_key: - description: - - PEM formatted file that contains your private key to be used for SSL client authentication. - - If O(client_cert) contains both the certificate and key, this option is not required. - type: path - version_added: '1.3.0' - keep_name: - description: - - If V(true), the downloaded artifact's name is preserved, i.e the version number remains part of it. - - This option only has effect when O(dest) is a directory and O(version) is set to V(latest) or O(version_by_spec) - is defined. - type: bool - default: false - verify_checksum: - type: str - description: - - If V(never), the MD5/SHA1 checksum will never be downloaded and verified. - - If V(download), the MD5/SHA1 checksum will be downloaded and verified only after artifact download. This is the default. - - If V(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist, - to verify if they are identical. This was the behaviour before 2.6. Since it downloads the checksum before (maybe) - downloading the artifact, and since some repository software, when acting as a proxy/cache, return a 404 error - if the artifact has not been cached yet, it may fail unexpectedly. - If you still need it, you should consider using V(always) instead - if you deal with a checksum, it is better to - use it to verify integrity after download. - - V(always) combines V(download) and V(change). - required: false - default: 'download' - choices: ['never', 'download', 'change', 'always'] - checksum_alg: - type: str - description: - - If V(md5), checksums will use the MD5 algorithm. This is the default. - - If V(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use - FIPS-compliant algorithms, since MD5 will be blocked on such systems. - default: 'md5' - choices: ['md5', 'sha1'] - version_added: 3.2.0 - unredirected_headers: - type: list - elements: str - version_added: 5.2.0 - description: - - A list of headers that should not be included in the redirection. This headers are sent to the C(fetch_url) function. - - On ansible-core version 2.12 or later, the default of this option is V([Authorization, Cookie]). - - Useful if the redirection URL does not need to have sensitive headers in the request. - - Requires ansible-core version 2.12 or later. - directory_mode: - type: str - description: - - Filesystem permission mode applied recursively to O(dest) when it is a directory. + group_id: + type: str + description: + - The Maven groupId coordinate. + required: true + artifact_id: + type: str + description: + - The maven artifactId coordinate. + required: true + version: + type: str + description: + - The maven version coordinate. + - Mutually exclusive with O(version_by_spec). + version_by_spec: + type: str + description: + - The maven dependency version ranges. + - See supported version ranges on U(https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution). + - The range type V((,1.0],[1.2,\)) and V((,1.1\),(1.1,\)) is not supported. + - Mutually exclusive with O(version). + version_added: '0.2.0' + classifier: + type: str + description: + - The maven classifier coordinate. + default: '' + extension: + type: str + description: + - The maven type/extension coordinate. + default: jar + repository_url: + type: str + description: + - The URL of the Maven Repository to download from. + - Use V(s3://...) if the repository is hosted on Amazon S3. + - Use V(file://...) if the repository is local. + default: https://repo1.maven.org/maven2 + username: + type: str + description: + - The username to authenticate as to the Maven Repository. Use AWS secret key of the repository is hosted on S3. + aliases: ["aws_secret_key"] + password: + type: str + description: + - The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on S3. + aliases: ["aws_secret_access_key"] + headers: + description: + - Add custom HTTP headers to a request in hash/dict format. + type: dict + force_basic_auth: + description: + - Httplib2, the library used by the uri module only sends authentication information when a webservice responds to an initial request with + a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This option forces the sending of the Basic + authentication header upon initial request. + default: false + type: bool + version_added: '0.2.0' + dest: + type: path + description: + - The path where the artifact should be written to. + - If file mode or ownerships are specified and destination path already exists, they affect the downloaded file. + required: true + state: + type: str + description: + - The desired state of the artifact. + default: present + choices: [present, absent] + timeout: + type: int + description: + - Specifies a timeout in seconds for the connection attempt. + default: 10 + validate_certs: + description: + - If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists. + type: bool + default: true + client_cert: + description: + - PEM formatted certificate chain file to be used for SSL client authentication. + - This file can also include the key as well, and if the key is included, O(client_key) is not required. + type: path + version_added: '1.3.0' + client_key: + description: + - PEM formatted file that contains your private key to be used for SSL client authentication. + - If O(client_cert) contains both the certificate and key, this option is not required. + type: path + version_added: '1.3.0' + keep_name: + description: + - If V(true), the downloaded artifact's name is preserved, in other words the version number remains part of it. + - This option only has effect when O(dest) is a directory and O(version) is set to V(latest) or O(version_by_spec) is defined. + type: bool + default: false + verify_checksum: + type: str + description: + - If V(never), the MD5/SHA1 checksum will never be downloaded and verified. + - If V(download), the MD5/SHA1 checksum will be downloaded and verified only after artifact download. This is the default. + - If V(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist, to verify if they are identical. + This was the behaviour before 2.6. Since it downloads the checksum before (maybe) downloading the artifact, and since some repository + software, when acting as a proxy/cache, return a 404 error if the artifact has not been cached yet, it may fail unexpectedly. If you still + need it, you should consider using V(always) instead - if you deal with a checksum, it is better to use it to verify integrity after download. + - V(always) combines V(download) and V(change). + required: false + default: 'download' + choices: ['never', 'download', 'change', 'always'] + checksum_alg: + type: str + description: + - If V(md5), checksums will use the MD5 algorithm. This is the default. + - If V(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use FIPS-compliant algorithms, since MD5 + will be blocked on such systems. + default: 'md5' + choices: ['md5', 'sha1'] + version_added: 3.2.0 + unredirected_headers: + type: list + elements: str + version_added: 5.2.0 + description: + - A list of headers that should not be included in the redirection. This headers are sent to the C(fetch_url) function. + - On ansible-core version 2.12 or later, the default of this option is V([Authorization, Cookie]). + - Useful if the redirection URL does not need to have sensitive headers in the request. + - Requires ansible-core version 2.12 or later. + directory_mode: + type: str + description: + - Filesystem permission mode applied recursively to O(dest) when it is a directory. extends_documentation_fragment: - - ansible.builtin.files - - community.general.attributes -''' + - ansible.builtin.files + - community.general.attributes +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Download the latest version of the JUnit framework artifact from Maven Central community.general.maven_artifact: group_id: junit @@ -236,7 +230,7 @@ EXAMPLES = ''' artifact_id: junit version_by_spec: "[3.8,4.0)" dest: /tmp/ -''' +""" import hashlib import os