From 3fc193485f85bc3a66a539e710c3f13efe3d7852 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky Date: Sun, 20 Jul 2025 09:19:27 +1200 Subject: [PATCH] doc style adjustments: modules m* --- plugins/modules/mail.py | 16 ++++---- plugins/modules/make.py | 2 +- plugins/modules/manageiq_group.py | 4 +- plugins/modules/manageiq_provider.py | 4 +- plugins/modules/manageiq_tags.py | 4 +- plugins/modules/manageiq_tags_info.py | 4 +- plugins/modules/manageiq_user.py | 4 +- plugins/modules/matrix.py | 2 +- plugins/modules/mattermost.py | 6 +-- plugins/modules/maven_artifact.py | 29 +++++++------- plugins/modules/memset_dns_reload.py | 6 +-- plugins/modules/memset_server_info.py | 2 +- plugins/modules/mksysb.py | 2 +- plugins/modules/modprobe.py | 10 ++--- plugins/modules/monit.py | 4 +- plugins/modules/mqtt.py | 16 ++++---- plugins/modules/mssql_script.py | 56 +++++++++++++++++++++++---- 17 files changed, 106 insertions(+), 65 deletions(-) diff --git a/plugins/modules/mail.py b/plugins/modules/mail.py index 03192e5bf8..382f1e4293 100644 --- a/plugins/modules/mail.py +++ b/plugins/modules/mail.py @@ -90,7 +90,7 @@ options: 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). + - Attached files have their content-type set to C(application/octet-stream). type: list elements: path default: [] @@ -115,12 +115,12 @@ options: default: plain secure: description: - - 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. + - If V(always), the connection only sends email if the connection is Encrypted. If the server does not accept the encrypted + connection it fails. + - If V(try), the connection attempts to setup a secure SSL/TLS session, before trying to send. + - If V(never), the connection does not attempt to setup a secure SSL/TLS session, before sending. + - If V(starttls), the connection tries to upgrade to a secure SSL/TLS connection, before sending. If it is unable to + do so it fails. type: str choices: [always, never, starttls, try] default: try @@ -137,7 +137,7 @@ options: message_id_domain: description: - The domain name to use for the L(Message-ID header, https://en.wikipedia.org/wiki/Message-ID). - - Note that this is only available on Python 3+. On Python 2, this value will be ignored. + - Note that this is only available on Python 3+. On Python 2, this value is ignored. type: str default: ansible version_added: 8.2.0 diff --git a/plugins/modules/make.py b/plugins/modules/make.py index a574560f7f..57ee525db5 100644 --- a/plugins/modules/make.py +++ b/plugins/modules/make.py @@ -48,7 +48,7 @@ options: params: description: - Any extra parameters to pass to make. - - If the value is empty, only the key will be used. For example, V(FOO:) will produce V(FOO), not V(FOO=). + - If the value is empty, only the key is used. For example, V(FOO:) produces V(FOO), not V(FOO=). type: dict target: description: diff --git a/plugins/modules/manageiq_group.py b/plugins/modules/manageiq_group.py index 9781ebfc98..4809992a7d 100644 --- a/plugins/modules/manageiq_group.py +++ b/plugins/modules/manageiq_group.py @@ -75,8 +75,8 @@ options: 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). + - In V(merge) mode existing categories are kept or updated, new categories are added. + - In V(replace) mode all categories are replaced with the supplied O(managed_filters). choices: [merge, replace] default: replace belongsto_filters: diff --git a/plugins/modules/manageiq_provider.py b/plugins/modules/manageiq_provider.py index 7f7049fa65..334555c29a 100644 --- a/plugins/modules/manageiq_provider.py +++ b/plugins/modules/manageiq_provider.py @@ -31,7 +31,7 @@ options: description: - V(absent) - provider should not exist, - V(present) - provider should be present, - - V(refresh) - provider will be refreshed. + - V(refresh) - provider is refreshed. choices: ['absent', 'present', 'refresh'] default: 'present' name: @@ -44,7 +44,7 @@ options: choices: ['Openshift', 'Amazon', 'oVirt', 'VMware', 'Azure', 'Director', 'OpenStack', 'GCE'] zone: type: str - description: The ManageIQ zone name that will manage the provider. + description: The ManageIQ zone name that manages the provider. default: 'default' provider_region: type: str diff --git a/plugins/modules/manageiq_tags.py b/plugins/modules/manageiq_tags.py index 6833b70355..40a0761a2a 100644 --- a/plugins/modules/manageiq_tags.py +++ b/plugins/modules/manageiq_tags.py @@ -63,11 +63,11 @@ options: resource_name: type: str description: - - The name of the resource at which tags will be controlled. + - The name of the resource at which tags are be controlled. - Must be specified if O(resource_id) is not set. Both options are mutually exclusive. resource_id: description: - - The ID of the resource at which tags will be controlled. + - The ID of the resource at which tags are controlled. - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. type: int version_added: 2.2.0 diff --git a/plugins/modules/manageiq_tags_info.py b/plugins/modules/manageiq_tags_info.py index c5b6fcd451..2a742f69c5 100644 --- a/plugins/modules/manageiq_tags_info.py +++ b/plugins/modules/manageiq_tags_info.py @@ -45,11 +45,11 @@ options: resource_name: type: str description: - - The name of the resource at which tags will be controlled. + - The name of the resource at which tags are controlled. - Must be specified if O(resource_id) is not set. Both options are mutually exclusive. resource_id: description: - - The ID of the resource at which tags will be controlled. + - The ID of the resource at which tags are controlled. - Must be specified if O(resource_name) is not set. Both options are mutually exclusive. type: int """ diff --git a/plugins/modules/manageiq_user.py b/plugins/modules/manageiq_user.py index a4d5c21dfc..475086c823 100644 --- a/plugins/modules/manageiq_user.py +++ b/plugins/modules/manageiq_user.py @@ -59,8 +59,8 @@ 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) updates passwords unconditionally. + - V(on_create) only sets the password for a newly created user. """ EXAMPLES = r""" diff --git a/plugins/modules/matrix.py b/plugins/modules/matrix.py index 186c57dd31..7336f36047 100644 --- a/plugins/modules/matrix.py +++ b/plugins/modules/matrix.py @@ -13,7 +13,7 @@ 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 attributes: diff --git a/plugins/modules/mattermost.py b/plugins/modules/mattermost.py index ed046e6481..15c0c5da2c 100644 --- a/plugins/modules/mattermost.py +++ b/plugins/modules/mattermost.py @@ -38,7 +38,7 @@ options: 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. U(http://mattermost.example.com/hooks/API_KEY). + Webhook. This gives you a full URL. O(api_key) is the last part. U(http://mattermost.example.com/hooks/API_KEY). required: true text: type: str @@ -75,8 +75,8 @@ options: 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 are not validated. This should only be used on personally controlled sites using self-signed + certificates. default: true type: bool """ diff --git a/plugins/modules/maven_artifact.py b/plugins/modules/maven_artifact.py index fb294797f0..91fc10d635 100644 --- a/plugins/modules/maven_artifact.py +++ b/plugins/modules/maven_artifact.py @@ -16,8 +16,7 @@ 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. + - Can retrieve snapshots or release versions of the artifact and resolve the latest available version if one is not available. author: "Chris Schmidt (@chrisisbeef)" requirements: - lxml @@ -85,8 +84,8 @@ options: type: dict force_basic_auth: description: - - C(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 + - C(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 fail. This option forces the sending of the Basic authentication header upon initial request. default: false type: bool @@ -110,7 +109,7 @@ options: 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. + - If V(false), SSL certificates are not validated. This should only be set to V(false) when no other option exists. type: bool default: true client_cert: @@ -135,13 +134,13 @@ options: 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. + - If V(never), the MD5/SHA1 checksum is never downloaded and verified. + - If V(download), the MD5/SHA1 checksum is downloaded and verified only after artifact download. This is the default. + - If V(change), the MD5/SHA1 checksum is 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' @@ -149,9 +148,9 @@ options: 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. + - If V(md5), checksums use the MD5 algorithm. This is the default. + - If V(sha1), checksums use the SHA1 algorithm. This can be used on systems configured to use FIPS-compliant algorithms, + since MD5 is blocked on such systems. default: 'md5' choices: ['md5', 'sha1'] version_added: 3.2.0 diff --git a/plugins/modules/memset_dns_reload.py b/plugins/modules/memset_dns_reload.py index 7781abbf76..782da2904b 100644 --- a/plugins/modules/memset_dns_reload.py +++ b/plugins/modules/memset_dns_reload.py @@ -36,9 +36,9 @@ options: default: false type: bool description: - - Boolean value, if set will poll the reload job's status and return when the job has completed (unless the 30 second - timeout is reached first). If the timeout is reached then the task will not be marked as failed, but stderr will indicate - that the polling failed. + - If V(true), it polls the reload job's status and return when the job has completed (unless the 30 second timeout is + reached first). If the timeout is reached then the task does not return as failed, but stderr indicates that the polling + failed. """ EXAMPLES = r""" diff --git a/plugins/modules/memset_server_info.py b/plugins/modules/memset_server_info.py index df7ecb712f..59d395a161 100644 --- a/plugins/modules/memset_server_info.py +++ b/plugins/modules/memset_server_info.py @@ -148,7 +148,7 @@ memset_api: description: The network zone(s) the server is in. returned: always type: list - sample: ['reading'] + sample: ["reading"] nickname: description: Customer-set nickname for the server. returned: always diff --git a/plugins/modules/mksysb.py b/plugins/modules/mksysb.py index 3b6d322f23..63301826de 100644 --- a/plugins/modules/mksysb.py +++ b/plugins/modules/mksysb.py @@ -77,7 +77,7 @@ options: storage_path: type: str description: - - Storage path where the mksysb will stored. + - Storage path where the mksysb backup is stored. required: true use_snapshot: description: diff --git a/plugins/modules/modprobe.py b/plugins/modules/modprobe.py index cff77e9558..d5bb6fddbb 100644 --- a/plugins/modules/modprobe.py +++ b/plugins/modules/modprobe.py @@ -50,11 +50,11 @@ options: - Persistency between reboots for configured module. - This option creates files in C(/etc/modules-load.d/) and C(/etc/modprobe.d/) that make your module configuration persistent during reboots. - - If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module will be - loaded on next reboot. - - If V(absent), will comment out module name from C(/etc/modules-load.d/) and comment out params from C(/etc/modprobe.d/) - so the module will not be loaded on next reboot. - - If V(disabled), will not touch anything and leave C(/etc/modules-load.d/) and C(/etc/modprobe.d/) as it is. + - If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module is loaded + on next reboot. + - If V(absent), comments out module name from C(/etc/modules-load.d/) and comments out params from C(/etc/modprobe.d/) + so the module is not loaded on next reboot. + - If V(disabled), does not touch anything and leaves C(/etc/modules-load.d/) and C(/etc/modprobe.d/) as it is. - Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar triggers encoded in the kernel modules themselves instead of configuration like this. - In fact, most modern kernel modules are prepared for automatic loading already. diff --git a/plugins/modules/monit.py b/plugins/modules/monit.py index 65b6c606e9..a10967264c 100644 --- a/plugins/modules/monit.py +++ b/plugins/modules/monit.py @@ -35,8 +35,8 @@ options: type: str timeout: description: - - If there are pending actions for the service monitored by monit, then Ansible will check for up to this many seconds - to verify the requested action has been performed. Ansible will sleep for five seconds between each check. + - If there are pending actions for the service monitored by monit, then it checks for up to this many seconds to verify + the requested action has been performed. The module sleeps for five seconds between each check. default: 300 type: int author: diff --git a/plugins/modules/mqtt.py b/plugins/modules/mqtt.py index 9c610d02c7..296ca74e82 100644 --- a/plugins/modules/mqtt.py +++ b/plugins/modules/mqtt.py @@ -44,7 +44,7 @@ options: type: str description: - MQTT client identifier. - - If not specified, a value C(hostname + pid) will be used. + - If not specified, it uses a value C(hostname + pid). topic: type: str description: @@ -72,22 +72,22 @@ options: type: path description: - The path to the Certificate Authority certificate files that are to be treated as trusted by this client. If this - is the only option given then the client will operate in a similar manner to a web browser. That is to say it will - require the broker to have a certificate signed by the Certificate Authorities in ca_certs and will communicate using - TLS v1, but will not attempt any form of authentication. This provides basic network encryption but may not be sufficient + is the only option given then the client operates in a similar manner to a web browser. That is to say it requires + the broker to have a certificate signed by the Certificate Authorities in ca_certs and communicates using TLS v1, + but does not attempt any form of authentication. This provides basic network encryption but may not be sufficient depending on how the broker is configured. aliases: [ca_certs] client_cert: type: path description: - - The path pointing to the PEM encoded client certificate. If this is not None it will be used as client information - for TLS based authentication. Support for this feature is broker dependent. + - The path pointing to the PEM encoded client certificate. If this is set it is used as client information for TLS based + authentication. Support for this feature is broker dependent. aliases: [certfile] client_key: type: path description: - - The path pointing to the PEM encoded client private key. If this is not None it will be used as client information - for TLS based authentication. Support for this feature is broker dependent. + - The path pointing to the PEM encoded client private key. If this is set it is used as client information for TLS based + authentication. Support for this feature is broker dependent. aliases: [keyfile] tls_version: description: diff --git a/plugins/modules/mssql_script.py b/plugins/modules/mssql_script.py index 872b2ee13d..e9914a4dd4 100644 --- a/plugins/modules/mssql_script.py +++ b/plugins/modules/mssql_script.py @@ -23,7 +23,7 @@ attributes: check_mode: support: partial details: - - The script will not be executed in check mode. + - The script is not be executed in check mode. diff_mode: support: none @@ -64,8 +64,8 @@ options: version_added: 8.4.0 output: description: - - With V(default) each row will be returned as a list of values. See RV(query_results). - - Output format V(dict) will return dictionary with the column names as keys. See RV(query_results_dict). + - With V(default) each row is returned as a list of values. See RV(query_results). + - Output format V(dict) returns dictionary with the column names as keys. See RV(query_results_dict). - V(dict) requires named columns to be returned by each query otherwise an error is thrown. choices: ["dict", "default"] default: 'default' @@ -170,12 +170,33 @@ query_results: type: list elements: list returned: success and O(output=default) - sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]] + sample: + [ + [ + [ + [ + "Batch 0 - Select 0" + ] + ], + [ + [ + "Batch 0 - Select 1" + ] + ] + ], + [ + [ + [ + "Batch 1 - Select 0" + ] + ] + ] + ] contains: queries: description: - List of result sets of each query. - - If a query returns no results, the results of this and all the following queries will not be included in the output. + - If a query returns no results, the results of this and all the following queries are not included in the output. - Use the V(GO) keyword in O(script) to separate queries. type: list elements: list @@ -197,12 +218,33 @@ query_results_dict: type: list elements: list returned: success and O(output=dict) - sample: [[[["Batch 0 - Select 0"]], [["Batch 0 - Select 1"]]], [[["Batch 1 - Select 0"]]]] + sample: + [ + [ + [ + [ + "Batch 0 - Select 0" + ] + ], + [ + [ + "Batch 0 - Select 1" + ] + ] + ], + [ + [ + [ + "Batch 1 - Select 0" + ] + ] + ] + ] contains: queries: description: - List of result sets of each query. - - If a query returns no results, the results of this and all the following queries will not be included in the output. + - If a query returns no results, the results of this and all the following queries are not included in the output. Use V(GO) keyword to separate queries. type: list elements: list