a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

t*: normalize docs (#9339) 

* t*: normalize docs

* Apply suggestions from code review

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

* break long line to regain sanity

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/9371/head
Alexei Znamensky 2024-12-24 23:59:56 +13:00 committed by GitHub
parent c141f86883
commit 6e84c1375e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 109 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
plugins/modules/taiga_issue.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: taiga_issue
short_description: Creates/deletes an issue in a Taiga Project Management Platform
description:
@ -89,10 +88,11 @@ options:
author: Alejandro Guirao (@lekum)
requirements: [python-taiga]
notes:
- The authentication is achieved either by the environment variable TAIGA_TOKEN or by the pair of environment variables TAIGA_USERNAME and TAIGA_PASSWORD
'''
- The authentication is achieved either by the environment variable E(TAIGA_TOKEN) or by the pair
of environment variables E(TAIGA_USERNAME) and E(TAIGA_PASSWORD).
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create an issue in the my hosted Taiga environment and attach an error log
community.general.taiga_issue:
taiga_host: https://mytaigahost.example.com
@ -117,9 +117,9 @@ EXAMPLES = '''
subject: An error has been found
issue_type: Bug
state: absent
'''
"""
RETURN = '''# '''
RETURN = """# """
import traceback
from os import getenv

16
plugins/modules/telegram.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: telegram
author:
- "Artem Feofanov (@tyouxa)"
@ -49,11 +48,9 @@ options:
- Any parameters for the method.
- For reference to default method, V(SendMessage), see U(https://core.telegram.org/bots/api#sendmessage).
version_added: 2.0.0
"""
'''
EXAMPLES = """
EXAMPLES = r"""
- name: Send notify to Telegram
community.general.telegram:
token: '9999999:XXXXXXXXXXXXXXXXXXXXXXX'
@ -75,15 +72,14 @@ EXAMPLES = """
message_id: '{{ saved_msg_id }}'
"""
RETURN = """
RETURN = r"""
msg:
description: The message you attempted to send
description: The message you attempted to send.
returned: success
type: str
sample: "Ansible task finished"
telegram_error:
description: Error message gotten from Telegram API
description: Error message gotten from Telegram API.
returned: failure
type: str
sample: "Bad Request: message text is empty"

82
plugins/modules/terraform.py
View File

@ -8,13 +8,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: terraform
short_description: Manages a Terraform deployment (and plans)
description:
- Provides support for deploying resources with Terraform and pulling
resource information back into Ansible.
- Provides support for deploying resources with Terraform and pulling resource information back into Ansible.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -27,18 +25,16 @@ options:
state:
choices: ['planned', 'present', 'absent']
description:
- Goal state of given stage/project
- Goal state of given stage/project.
type: str
default: present
binary_path:
description:
- The path of a terraform binary to use, relative to the 'service_path'
unless you supply an absolute path.
- The path of a C(terraform) binary to use, relative to the 'service_path' unless you supply an absolute path.
type: path
project_path:
description:
- The path to the root of the Terraform directory with the
vars.tf/main.tf/etc to use.
- The path to the root of the Terraform directory with the C(vars.tf)/C(main.tf)/etc to use.
type: path
required: true
plugin_paths:
@ -48,88 +44,80 @@ options:
- When set, the plugin discovery and auto-download behavior of Terraform is disabled.
- The directory structure in the plugin path can be tricky. The Terraform docs
U(https://learn.hashicorp.com/tutorials/terraform/automate-terraform#pre-installed-plugins)
show a simple directory of files, but actually, the directory structure
has to follow the same structure you would see if Terraform auto-downloaded the plugins.
See the examples below for a tree output of an example plugin directory.
show a simple directory of files, but actually, the directory structure has to follow the same structure you would see if Terraform auto-downloaded
the plugins. See the examples below for a tree output of an example plugin directory.
type: list
elements: path
version_added: 3.0.0
workspace:
description:
- The terraform workspace to work with. This sets the E(TF_WORKSPACE) environmental variable
that is used to override workspace selection. For more information about workspaces
have a look at U(https://developer.hashicorp.com/terraform/language/state/workspaces).
- The terraform workspace to work with. This sets the E(TF_WORKSPACE) environmental variable that is used to override workspace selection.
For more information about workspaces have a look at U(https://developer.hashicorp.com/terraform/language/state/workspaces).
type: str
default: default
purge_workspace:
description:
- Only works with state = absent
- Only works with state = absent.
- If true, the workspace will be deleted after the "terraform destroy" action.
- The 'default' workspace will not be deleted.
default: false
type: bool
plan_file:
description:
- The path to an existing Terraform plan file to apply. If this is not
specified, Ansible will build a new TF plan and execute it.
Note that this option is required if 'state' has the 'planned' value.
- The path to an existing Terraform plan file to apply. If this is not specified, Ansible will build a new TF plan and execute it. Note
that this option is required if 'state' has the 'planned' value.
type: path
state_file:
description:
- The path to an existing Terraform state file to use when building plan.
If this is not specified, the default C(terraform.tfstate) will be used.
- The path to an existing Terraform state file to use when building plan. If this is not specified, the default C(terraform.tfstate) will
be used.
- This option is ignored when plan is specified.
type: path
variables_files:
description:
- The path to a variables file for Terraform to fill into the TF
configurations. This can accept a list of paths to multiple variables files.
- The path to a variables file for Terraform to fill into the TF configurations. This can accept a list of paths to multiple variables files.
type: list
elements: path
aliases: ['variables_file']
variables:
description:
- A group of key-values pairs to override template variables or those in variables files.
By default, only string and number values are allowed, which are passed on unquoted.
- A group of key-values pairs to override template variables or those in variables files. By default, only string and number values are
allowed, which are passed on unquoted.
- Support complex variable structures (lists, dictionaries, numbers, and booleans) to reflect terraform variable syntax when O(complex_vars=true).
- Ansible integers or floats are mapped to terraform numbers.
- Ansible strings are mapped to terraform strings.
- Ansible dictionaries are mapped to terraform objects.
- Ansible lists are mapped to terraform lists.
- Ansible booleans are mapped to terraform booleans.
- "B(Note) passwords passed as variables will be visible in the log output. Make sure to use C(no_log=true) in production!"
- B(Note) passwords passed as variables will be visible in the log output. Make sure to use C(no_log=true) in production!.
type: dict
complex_vars:
description:
- Enable/disable capability to handle complex variable structures for C(terraform).
- If V(true) the O(variables) also accepts dictionaries, lists, and booleans to be passed to C(terraform).
Strings that are passed are correctly quoted.
- If V(true) the O(variables) also accepts dictionaries, lists, and booleans to be passed to C(terraform). Strings that are passed are correctly
quoted.
- When disabled, supports only simple variables (strings, integers, and floats), and passes them on unquoted.
type: bool
default: false
version_added: 5.7.0
targets:
description:
- A list of specific resources to target in this plan/application. The
resources selected here will also auto-include any dependencies.
- A list of specific resources to target in this plan/application. The resources selected here will also auto-include any dependencies.
type: list
elements: str
default: []
lock:
description:
- Enable statefile locking, if you use a service that accepts locks (such
as S3+DynamoDB) to store your statefile.
- Enable statefile locking, if you use a service that accepts locks (such as S3+DynamoDB) to store your statefile.
type: bool
default: true
lock_timeout:
description:
- How long to maintain the lock on the statefile, if you use a service
that accepts locks (such as S3+DynamoDB).
- How long to maintain the lock on the statefile, if you use a service that accepts locks (such as S3+DynamoDB).
type: int
force_init:
description:
- To avoid duplicating infra, if a state file can't be found this will
force a C(terraform init). Generally, this should be turned off unless
- To avoid duplicating infra, if a state file can't be found this will force a C(terraform init). Generally, this should be turned off unless
you intend to provision an entirely new Terraform deployment.
default: false
type: bool
@ -145,8 +133,8 @@ options:
type: dict
backend_config_files:
description:
- The path to a configuration file to provide at init state to the -backend-config parameter.
This can accept a list of paths to multiple configuration files.
- The path to a configuration file to provide at init state to the -backend-config parameter. This can accept a list of paths to multiple
configuration files.
type: list
elements: path
version_added: '0.2.0'
@ -164,8 +152,8 @@ options:
version_added: '1.3.0'
check_destroy:
description:
- Apply only when no resources are destroyed. Note that this only prevents "destroy" actions,
but not "destroy and re-create" actions. This option is ignored when O(state=absent).
- Apply only when no resources are destroyed. Note that this only prevents "destroy" actions, but not "destroy and re-create" actions. This
option is ignored when O(state=absent).
type: bool
default: false
version_added: '3.3.0'
@ -178,9 +166,9 @@ notes:
- To just run a C(terraform plan), use check mode.
requirements: ["terraform"]
author: "Ryan Scott Brown (@ryansb)"
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Basic deploy of a service
community.general.terraform:
project_path: '{{ project_dir }}'
@ -248,7 +236,7 @@ EXAMPLES = """
# └── terraform-provider-vsphere_v1.26.0_x4
"""
RETURN = """
RETURN = r"""
outputs:
type: complex
description: A dictionary of all the TF outputs by their assigned name. Use RV(ignore:outputs.MyOutputName.value) to access the value.
@ -258,18 +246,18 @@ outputs:
sensitive:
type: bool
returned: always
description: Whether Terraform has marked this value as sensitive
description: Whether Terraform has marked this value as sensitive.
type:
type: str
returned: always
description: The type of the value (string, int, etc)
description: The type of the value (string, int, etc).
value:
type: str
returned: always
description: The value of the output as interpolated by Terraform
description: The value of the output as interpolated by Terraform.
stdout:
type: str
description: Full C(terraform) command stdout, in case you want to display it or examine the event log
description: Full C(terraform) command stdout, in case you want to display it or examine the event log.
returned: always
sample: ''
command:

46
plugins/modules/timezone.py
View File

@ -8,20 +8,18 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: timezone
short_description: Configure timezone setting
description:
- This module configures the timezone setting, both of the system clock and of the hardware clock.
If you want to set up the NTP, use M(ansible.builtin.service) module.
- This module configures the timezone setting, both of the system clock and of the hardware clock. If you want to set up the NTP, use
M(ansible.builtin.service) module.
- It is recommended to restart C(crond) after changing the timezone, otherwise the jobs may run at the wrong time.
- Several different tools are used depending on the OS/Distribution involved.
For Linux it can use C(timedatectl) or edit C(/etc/sysconfig/clock) or C(/etc/timezone) and C(hwclock).
On SmartOS, C(sm-set-timezone), for macOS, C(systemsetup), for BSD, C(/etc/localtime) is modified.
On AIX, C(chtz) is used.
- Make sure that the zoneinfo files are installed with the appropriate OS package, like C(tzdata) (usually always installed,
when not using a minimal installation like Alpine Linux).
- Several different tools are used depending on the OS/Distribution involved. For Linux it can use C(timedatectl) or edit C(/etc/sysconfig/clock)
or C(/etc/timezone) and C(hwclock). On SmartOS, C(sm-set-timezone), for macOS, C(systemsetup), for BSD, C(/etc/localtime) is modified. On
AIX, C(chtz) is used.
- Make sure that the zoneinfo files are installed with the appropriate OS package, like C(tzdata) (usually always installed, when not using
a minimal installation like Alpine Linux).
- Windows and HPUX are not supported, please let us know if you find any other OS/distro in which this fails.
extends_documentation_fragment:
- community.general.attributes
@ -35,51 +33,49 @@ options:
description:
- Name of the timezone for the system clock.
- Default is to keep current setting.
- B(At least one of name and hwclock are required.)
- B(At least one) of O(name) and O(hwclock) are required.
type: str
hwclock:
description:
- Whether the hardware clock is in UTC or in local timezone.
- Default is to keep current setting.
- Note that this option is recommended not to change and may fail
to configure, especially on virtual environments such as AWS.
- B(At least one of name and hwclock are required.)
- I(Only used on Linux.)
- Note that this option is recommended not to change and may fail to configure, especially on virtual environments such as AWS.
- B(At least one) of O(name) and O(hwclock) are required.
- I(Only used on Linux).
type: str
aliases: [rtc]
choices: [local, UTC]
notes:
- On Ubuntu 24.04 the C(util-linux-extra) package is required to provide the C(hwclock) command.
- On SmartOS the C(sm-set-timezone) utility (part of the smtools package) is required to set the zone timezone.
- On AIX only Olson/tz database timezones are usable (POSIX is not supported).
An OS reboot is also required on AIX for the new timezone setting to take effect.
Note that AIX 6.1+ is needed (OS level 61 or newer).
- On AIX only Olson/tz database timezones are usable (POSIX is not supported). An OS reboot is also required on AIX for the new timezone setting
to take effect. Note that AIX 6.1+ is needed (OS level 61 or newer).
author:
- Shinichi TAMURA (@tmshn)
- Jasper Lievisse Adriaanse (@jasperla)
- Indrajit Raychaudhuri (@indrajitr)
'''
"""
RETURN = r'''
RETURN = r"""
diff:
description: The differences about the given arguments.
returned: success
type: complex
contains:
before:
description: The values before change
description: The values before change.
type: dict
after:
description: The values after change
description: The values after change.
type: dict
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Set timezone to Asia/Tokyo
become: true
community.general.timezone:
name: Asia/Tokyo
'''
"""
import errno
import os

36
plugins/modules/twilio.py
View File

@ -9,18 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: twilio
short_description: Sends a text message to a mobile phone through Twilio
description:
- Sends a text message to a phone number through the Twilio messaging API.
notes:
- This module is non-idempotent because it sends an email through the
external API. It is idempotent only in the case that the module fails.
- Like the other notification modules, this one requires an external
dependency to work. In this case, you'll need a Twilio account with
a purchased or verified phone number to send the text message.
- This module is non-idempotent because it sends an email through the external API. It is idempotent only in the case that the module fails.
- Like the other notification modules, this one requires an external dependency to work. In this case, you'll need a Twilio account with a purchased
or verified phone number to send the text message.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -59,14 +56,13 @@ options:
media_url:
type: str
description:
- A URL with a picture, video or sound clip to send with an MMS
(multimedia message) instead of a plain SMS.
- A URL with a picture, video or sound clip to send with an MMS (multimedia message) instead of a plain SMS.
required: false
author: "Matt Makai (@makaimc)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# send an SMS about the build status to (555) 303 5681
# note: replace account_sid and auth_token values with your credentials
# and you have to have the 'from_number' on your Twilio account
@ -75,8 +71,8 @@ EXAMPLES = '''
msg: All servers with webserver role are now configured.
account_sid: ACXXXXXXXXXXXXXXXXX
auth_token: ACXXXXXXXXXXXXXXXXX
from_number: +15552014545
to_number: +15553035681
from_number: "+15552014545"
to_number: "+15553035681"
delegate_to: localhost
# send an SMS to multiple phone numbers about the deployment
@ -87,11 +83,11 @@ EXAMPLES = '''
msg: This server configuration is now complete.
account_sid: ACXXXXXXXXXXXXXXXXX
auth_token: ACXXXXXXXXXXXXXXXXX
from_number: +15553258899
from_number: "+15553258899"
to_numbers:
- +15551113232
- +12025551235
- +19735559010
- "+15551113232"
- "+12025551235"
- "+19735559010"
delegate_to: localhost
# send an MMS to a single recipient with an update on the deployment
@ -103,11 +99,11 @@ EXAMPLES = '''
msg: Deployment complete!
account_sid: ACXXXXXXXXXXXXXXXXX
auth_token: ACXXXXXXXXXXXXXXXXX
from_number: +15552014545
to_number: +15553035681
from_number: "+15552014545"
to_number: "+15553035681"
media_url: https://demo.twilio.com/logo.png
delegate_to: localhost
'''
"""
# =======================================
# twilio module support methods

19
plugins/modules/typetalk.py
View File

@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: typetalk
short_description: Send a message to typetalk
description:
- Send a message to typetalk using typetalk API
- Send a message to typetalk using typetalk API.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -26,35 +25,35 @@ options:
client_id:
type: str
description:
- OAuth2 client ID
- OAuth2 client ID.
required: true
client_secret:
type: str
description:
- OAuth2 client secret
- OAuth2 client secret.
required: true
topic:
type: int
description:
- topic id to post message
- Topic id to post message.
required: true
msg:
type: str
description:
- message body
- Message body.
required: true
requirements: [json]
author: "Takashi Someda (@tksmd)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Send a message to typetalk
community.general.typetalk:
client_id: 12345
client_secret: 12345
topic: 1
msg: install completed
'''
"""
import json