ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

[PR #6671/6fc1df9b backport][stable-7] Use semantic markup (modules a-c) (#6701)

Browse source 
Use semantic markup (modules a-c) (#6671)

* Use semantic markup.

* E() now works better.

(cherry picked from commit 6fc1df9b83)

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
patchback[bot] 2023-06-15 19:04:07 +02:00 committed by GitHub
parent 6789f7939a
commit ecf6f585ee
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
32 changed files with 193 additions and 200 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
plugins/lookup/dependent.py
View file

@ -22,7 +22,7 @@ options:
The name is the index that is used in the result object. The value is iterated over as described below.
- If the value is a list, it is simply iterated over.
- If the value is a dictionary, it is iterated over and returned as if they would be processed by the
R(ansible.builtin.dict2items filter,ansible_collections.ansible.builtin.dict2items_filter).
P(ansible.builtin.dict2items#filter) filter.
- If the value is a string, it is evaluated as Jinja2 expressions which can access the previously chosen
elements with C(item.<index_name>). The result must be a list or a dictionary.
type: list

2
plugins/lookup/flattened.py
View file

@ -19,7 +19,7 @@ DOCUMENTATION = '''
elements: raw
required: true
notes:
- Unlike the R(items lookup,ansible_collections.ansible.builtin.items_lookup) which only flattens 1 level,
- Unlike the P(ansible.builtin.items#lookup) lookup which only flattens 1 level,
this plugin will continue to flatten until it cannot find lists anymore.
- Aka highlander plugin, there can only be one (list).
'''

2
plugins/modules/alerta_customer.py
View file

@ -58,7 +58,7 @@ options:
state:
description:
- Whether the customer should exist or not.
- Both I(customer) and I(match) identify a customer that should be added or removed.
- Both O(customer) and O(match) identify a customer that should be added or removed.
type: str
choices: [ absent, present ]
default: present

28
plugins/modules/ali_instance.py
View file

@ -51,12 +51,12 @@ options:
type: str
image_id:
description:
- Image ID used to launch instances. Required when I(state=present) and creating new ECS instances.
- Image ID used to launch instances. Required when O(state=present) and creating new ECS instances.
aliases: ['image']
type: str
instance_type:
description:
- Instance type used to launch instances. Required when I(state=present) and creating new ECS instances.
- Instance type used to launch instances. Required when O(state=present) and creating new ECS instances.
aliases: ['type']
type: str
security_groups:
@ -95,7 +95,7 @@ options:
max_bandwidth_out:
description:
- Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second).
Required when I(allocate_public_ip=true). Ignored when I(allocate_public_ip=false).
Required when O(allocate_public_ip=true). Ignored when O(allocate_public_ip=false).
default: 0
type: int
host_name:
@ -134,16 +134,16 @@ options:
type: str
count:
description:
- The number of the new instance. An integer value which indicates how many instances that match I(count_tag)
- The number of the new instance. An integer value which indicates how many instances that match O(count_tag)
should be running. Instances are either created or terminated based on this value.
default: 1
type: int
count_tag:
description:
- I(count) determines how many instances based on a specific tag criteria should be present.
- O(count) determines how many instances based on a specific tag criteria should be present.
This can be expressed in multiple ways and is shown in the EXAMPLES section.
The specified count_tag must already exist or be passed in as the I(tags) option.
If it is not specified, it will be replaced by I(instance_name).
The specified count_tag must already exist or be passed in as the O(tags) option.
If it is not specified, it will be replaced by O(instance_name).
type: str
allocate_public_ip:
description:
@ -159,7 +159,7 @@ options:
type: str
period:
description:
- The charge duration of the instance, in months. Required when I(instance_charge_type=PrePaid).
- The charge duration of the instance, in months. Required when O(instance_charge_type=PrePaid).
- The valid value are [1-9, 12, 24, 36].
default: 1
type: int
@ -170,13 +170,13 @@ options:
default: false
auto_renew_period:
description:
- The duration of the automatic renew the charge of the instance. Required when I(auto_renew=true).
- The duration of the automatic renew the charge of the instance. Required when O(auto_renew=true).
choices: [1, 2, 3, 6, 12]
type: int
instance_ids:
description:
- A list of instance ids. It is required when need to operate existing instances.
If it is specified, I(count) will lose efficacy.
If it is specified, O(count) will lose efficacy.
type: list
elements: str
force:
@ -186,7 +186,7 @@ options:
type: bool
tags:
description:
- A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. C({"key":"value"})
- A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. V({"key":"value"})
aliases: ["instance_tags"]
type: dict
version_added: '0.2.0'
@ -229,7 +229,7 @@ options:
version_added: '0.2.0'
period_unit:
description:
- The duration unit that you will buy the resource. It is valid when I(instance_charge_type=PrePaid).
- The duration unit that you will buy the resource. It is valid when O(instance_charge_type=PrePaid).
choices: ['Month', 'Week']
default: 'Month'
type: str
@ -237,10 +237,10 @@ options:
dry_run:
description:
- Specifies whether to send a dry-run request.
- If I(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the
- If O(dry_run=true), Only a dry-run request is sent and no instance is created. The system checks whether the
required parameters are set, and validates the request format, service permissions, and available ECS instances.
If the validation fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned.
- If I(dry_run=false), A request is sent. If the validation succeeds, the instance is created.
- If O(dry_run=false), A request is sent. If the validation succeeds, the instance is created.
default: false
type: bool
version_added: '0.2.0'

6
plugins/modules/ali_instance_info.py
View file

@ -53,9 +53,9 @@ options:
description:
- A dict of filters to apply. Each dict item consists of a filter key and a filter value. The filter keys can be
all of request parameters. See U(https://www.alibabacloud.com/help/doc-detail/25506.htm) for parameter details.
Filter keys can be same as request parameter name or be lower case and use underscore ("_") or dash ("-") to
connect different words in one parameter. 'InstanceIds' should be a list.
'Tag.n.Key' and 'Tag.n.Value' should be a dict and using I(tags) instead.
Filter keys can be same as request parameter name or be lower case and use underscore (V("_")) or dash (V("-")) to
connect different words in one parameter. C(InstanceIds) should be a list.
C(Tag.n.Key) and C(Tag.n.Value) should be a dict and using O(tags) instead.
type: dict
version_added: '0.2.0'
author:

12
plugins/modules/alternatives.py
View file

@ -44,21 +44,21 @@ options:
description:
- The path to the symbolic link that should point to the real executable.
- This option is always required on RHEL-based distributions. On Debian-based distributions this option is
required when the alternative I(name) is unknown to the system.
required when the alternative O(name) is unknown to the system.
type: path
priority:
description:
- The priority of the alternative. If no priority is given for creation C(50) is used as a fallback.
- The priority of the alternative. If no priority is given for creation V(50) is used as a fallback.
type: int
state:
description:
- C(present) - install the alternative (if not already installed), but do
- V(present) - install the alternative (if not already installed), but do
not set it as the currently selected alternative for the group.
- C(selected) - install the alternative (if not already installed), and
- V(selected) - install the alternative (if not already installed), and
set it as the currently selected alternative for the group.
- C(auto) - install the alternative (if not already installed), and
- V(auto) - install the alternative (if not already installed), and
set the group to auto mode. Added in community.general 5.1.0.
- C(absent) - removes the alternative. Added in community.general 5.1.0.
- V(absent) - removes the alternative. Added in community.general 5.1.0.
choices: [ present, selected, auto, absent ]
default: selected
type: str

46
plugins/modules/ansible_galaxy_install.py
View file

@ -37,9 +37,9 @@ options:
type:
description:
- The type of installation performed by C(ansible-galaxy).
- If I(type) is C(both), then I(requirements_file) must be passed and it may contain both roles and collections.
- "Note however that the opposite is not true: if using a I(requirements_file), then I(type) can be any of the three choices."
- "B(Ansible 2.9): The option C(both) will have the same effect as C(role)."
- If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections.
- "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices."
- "B(Ansible 2.9): The option V(both) will have the same effect as V(role)."
type: str
choices: [collection, role, both]
required: true
@ -48,22 +48,22 @@ options:
- Name of the collection or role being installed.
- >
Versions can be specified with C(ansible-galaxy) usual formats.
For example, the collection C(community.docker:1.6.1) or the role C(ansistrano.deploy,3.8.0).
- I(name) and I(requirements_file) are mutually exclusive.
For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0).
- O(name) and O(requirements_file) are mutually exclusive.
type: str
requirements_file:
description:
- Path to a file containing a list of requirements to be installed.
- It works for I(type) equals to C(collection) and C(role).
- I(name) and I(requirements_file) are mutually exclusive.
- "B(Ansible 2.9): It can only be used to install either I(type=role) or I(type=collection), but not both at the same run."
- It works for O(type) equals to V(collection) and V(role).
- O(name) and O(requirements_file) are mutually exclusive.
- "B(Ansible 2.9): It can only be used to install either O(type=role) or O(type=collection), but not both at the same run."
type: path
dest:
description:
- The path to the directory containing your collections or roles, according to the value of I(type).
- The path to the directory containing your collections or roles, according to the value of O(type).
- >
Please notice that C(ansible-galaxy) will not install collections with I(type=both), when I(requirements_file)
contains both roles and collections and I(dest) is specified.
Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file)
contains both roles and collections and O(dest) is specified.
type: path
no_deps:
description:
@ -74,8 +74,8 @@ options:
force:
description:
- Force overwriting an existing role or collection.
- Using I(force=true) is mandatory when downgrading.
- "B(Ansible 2.9 and 2.10): Must be C(true) to upgrade roles and collections."
- Using O(force=true) is mandatory when downgrading.
- "B(Ansible 2.9 and 2.10): Must be V(true) to upgrade roles and collections."
type: bool
default: false
ack_ansible29:
@ -92,7 +92,7 @@ options:
- Support for those versions will be removed in community.general 8.0.0.
At the same time, this option will be removed without any deprecation warning!
- This option is completely ignored if using a version of ansible-core/ansible-base/Ansible greater than C(2.11).
- For the sake of conciseness, setting this parameter to C(true) implies I(ack_ansible29=true).
- For the sake of conciseness, setting this parameter to V(true) implies O(ack_ansible29=true).
type: bool
default: false
"""
@ -124,29 +124,29 @@ EXAMPLES = """
RETURN = """
type:
description: The value of the I(type) parameter.
description: The value of the O(type) parameter.
type: str
returned: always
name:
description: The value of the I(name) parameter.
description: The value of the O(name) parameter.
type: str
returned: always
dest:
description: The value of the I(dest) parameter.
description: The value of the O(dest) parameter.
type: str
returned: always
requirements_file:
description: The value of the I(requirements_file) parameter.
description: The value of the O(requirements_file) parameter.
type: str
returned: always
force:
description: The value of the I(force) parameter.
description: The value of the O(force) parameter.
type: bool
returned: always
installed_roles:
description:
- If I(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
- If I(name) is specified, returns that role name and the version installed per path.
- If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
- If O(name) is specified, returns that role name and the version installed per path.
- "B(Ansible 2.9): Returns empty because C(ansible-galaxy) has no C(list) subcommand."
type: dict
returned: always when installing roles
@ -162,8 +162,8 @@ RETURN = """
ansistrano.deploy: 3.8.0
installed_collections:
description:
- If I(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
- If I(name) is specified, returns that collection name and the version installed per path.
- If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path.
- If O(name) is specified, returns that collection name and the version installed per path.
- "B(Ansible 2.9): Returns empty because C(ansible-galaxy) has no C(list) subcommand."
type: dict
returned: always when installing collections

2
plugins/modules/apache2_module.py
View file

@ -37,7 +37,7 @@ options:
description:
- Identifier of the module as listed by C(apache2ctl -M).
This is optional and usually determined automatically by the common convention of
appending C(_module) to I(name) as well as custom exception for popular modules.
appending V(_module) to O(name) as well as custom exception for popular modules.
required: false
force:
description:

14
plugins/modules/apk.py
View file

@ -17,7 +17,7 @@ DOCUMENTATION = '''
module: apk
short_description: Manages apk packages
description:
- Manages I(apk) packages for Alpine Linux.
- Manages C(apk) packages for Alpine Linux.
author: "Kevin Brebanov (@kbrebanov)"
extends_documentation_fragment:
- community.general.attributes
@ -35,7 +35,7 @@ options:
default: false
name:
description:
- A package name, like C(foo), or multiple packages, like C(foo, bar).
- A package name, like V(foo), or multiple packages, like V(foo, bar).
type: list
elements: str
no_cache:
@ -53,9 +53,9 @@ options:
state:
description:
- Indicates the desired package(s) state.
- C(present) ensures the package(s) is/are present. C(installed) can be used as an alias.
- C(absent) ensures the package(s) is/are absent. C(removed) can be used as an alias.
- C(latest) ensures the package(s) is/are present and the latest version(s).
- V(present) ensures the package(s) is/are present. V(installed) can be used as an alias.
- V(absent) ensures the package(s) is/are absent. V(removed) can be used as an alias.
- V(latest) ensures the package(s) is/are present and the latest version(s).
default: present
choices: [ "present", "absent", "latest", "installed", "removed" ]
type: str
@ -76,8 +76,8 @@ options:
default: /etc/apk/world
version_added: 5.4.0
notes:
- 'I(name) and I(upgrade) are mutually exclusive.'
- When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the I(name) option.
- 'O(name) and O(upgrade) are mutually exclusive.'
- When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
'''
EXAMPLES = '''

2
plugins/modules/apt_repo.py
View file

@ -41,7 +41,7 @@ options:
remove_others:
description:
- Remove other then added repositories
- Used if I(state=present)
- Used if O(state=present)
type: bool
default: false
update:

2
plugins/modules/apt_rpm.py
View file

@ -16,7 +16,7 @@ DOCUMENTATION = '''
module: apt_rpm
short_description: APT-RPM package manager
description:
- Manages packages with I(apt-rpm). Both low-level (I(rpm)) and high-level (I(apt-get)) package manager binaries required.
- Manages packages with C(apt-rpm). Both low-level (C(rpm)) and high-level (C(apt-get)) package manager binaries required.
extends_documentation_fragment:
- community.general.attributes
attributes:

16
plugins/modules/archive.py
View file

@ -20,7 +20,7 @@ extends_documentation_fragment:
description:
- Creates or extends an archive.
- The source and archive are on the remote host, and the archive I(is not) copied to the local host.
- Source files can be deleted after archival by specifying I(remove=True).
- Source files can be deleted after archival by specifying O(remove=True).
attributes:
check_mode:
support: full
@ -43,20 +43,20 @@ options:
dest:
description:
- The file name of the destination archive. The parent directory must exists on the remote host.
- This is required when C(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list.
- This is required when O(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list.
- If the destination archive already exists, it will be truncated and overwritten.
type: path
exclude_path:
description:
- Remote absolute path, glob, or list of paths or globs for the file or files to exclude from I(path) list and glob expansion.
- Use I(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the I(path) list.
- Remote absolute path, glob, or list of paths or globs for the file or files to exclude from O(path) list and glob expansion.
- Use O(exclusion_patterns) to instead exclude files or subdirectories below any of the paths from the O(path) list.
type: list
elements: path
default: []
exclusion_patterns:
description:
- Glob style patterns to exclude files or directories from the resulting archive.
- This differs from I(exclude_path) which applies only to the source paths from I(path).
- This differs from O(exclude_path) which applies only to the source paths from O(path).
type: list
elements: path
version_added: 3.2.0
@ -73,7 +73,7 @@ options:
type: bool
default: false
notes:
- Can produce I(gzip), I(bzip2), I(lzma), and I(zip) compressed files or archives.
- Can produce C(gzip), C(bzip2), C(lzma), and C(zip) compressed files or archives.
- This module uses C(tarfile), C(zipfile), C(gzip), and C(bz2) packages on the target host to create archives.
These are part of the Python standard library for Python 2 and 3.
requirements:
@ -149,11 +149,11 @@ state:
returned: always
dest_state:
description:
- The state of the I(dest) file.
- The state of the O(dest) file.
- C(absent) when the file does not exist.
- C(archive) when the file is an archive.
- C(compress) when the file is compressed, but not an archive.
- C(incomplete) when the file is an archive, but some files under I(path) were not found.
- C(incomplete) when the file is an archive, but some files under O(path) were not found.
type: str
returned: success
version_added: 3.4.0

6
plugins/modules/awall.py
View file

@ -16,7 +16,7 @@ short_description: Manage awall policies
author: Ted Trask (@tdtrask) <ttrask01@yahoo.com>
description:
- This modules allows for enable/disable/activate of C(awall) policies.
- Alpine Wall (I(awall)) generates a firewall configuration from the enabled policy files
- Alpine Wall (C(awall)) generates a firewall configuration from the enabled policy files
and activates the configuration on the system.
extends_documentation_fragment:
- community.general.attributes
@ -41,11 +41,11 @@ options:
description:
- Activate the new firewall rules.
- Can be run with other steps or on its own.
- Idempotency is affected if I(activate=true), as the module will always report a changed state.
- Idempotency is affected if O(activate=true), as the module will always report a changed state.
type: bool
default: false
notes:
- At least one of I(name) and I(activate) is required.
- At least one of O(name) and O(activate) is required.
'''
EXAMPLES = r'''

6
plugins/modules/bearychat.py
View file

@ -27,7 +27,7 @@ options:
description:
- BearyChat WebHook URL. This authenticates you to the bearychat
service. It looks like
C(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60).
V(https://hook.bearychat.com/=ae2CF/incoming/e61bd5c57b164e04b11ac02e66f47f60).
required: true
text:
type: str
@ -35,14 +35,14 @@ options:
- Message to send.
markdown:
description:
- If C(true), text will be parsed as markdown.
- If V(true), text will be parsed as markdown.
default: true
type: bool
channel:
type: str
description:
- Channel to send the message to. If absent, the message goes to the
default channel selected by the I(url).
default channel selected by the O(url).
attachments:
type: list
elements: dict

2
plugins/modules/bitbucket_access_key.py
View file

@ -33,7 +33,7 @@ options:
workspace:
description:
- The repository owner.
- I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
- "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
type: str
required: true
key:

2
plugins/modules/bitbucket_pipeline_key_pair.py
View file

@ -33,7 +33,7 @@ options:
workspace:
description:
- The repository owner.
- I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
- "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
type: str
required: true
public_key:

4
plugins/modules/bitbucket_pipeline_known_host.py
View file

@ -14,7 +14,7 @@ module: bitbucket_pipeline_known_host
short_description: Manages Bitbucket pipeline known hosts
description:
- Manages Bitbucket pipeline known hosts under the "SSH Keys" menu.
- The host fingerprint will be retrieved automatically, but in case of an error, one can use I(key) field to specify it manually.
- The host fingerprint will be retrieved automatically, but in case of an error, one can use O(key) field to specify it manually.
author:
- Evgeniy Krysanov (@catcombo)
extends_documentation_fragment:
@ -36,7 +36,7 @@ options:
workspace:
description:
- The repository owner.
- I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
- "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
type: str
required: true
name:

4
plugins/modules/bitbucket_pipeline_variable.py
View file

@ -33,7 +33,7 @@ options:
workspace:
description:
- The repository owner.
- I(username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of I(user).
- "B(Note:) O(ignore:username) used to be an alias of this option. Since community.general 6.0.0 it is an alias of O(user)."
type: str
required: true
name:
@ -58,7 +58,7 @@ options:
choices: [ absent, present ]
notes:
- Check mode is supported.
- For secured values return parameter C(changed) is always C(True).
- For secured values return parameter C(changed) is always V(true).
'''
EXAMPLES = r'''

14
plugins/modules/btrfs_subvolume.py
View file

@ -23,7 +23,7 @@ options:
default: false
default:
description:
- Make the subvolume specified by I(name) the filesystem's default subvolume.
- Make the subvolume specified by O(name) the filesystem's default subvolume.
type: bool
default: false
filesystem_device:
@ -49,7 +49,7 @@ options:
recursive:
description:
- When true, indicates that parent/child subvolumes should be created/removedas necessary
to complete the operation (for I(state=present) and I(state=absent) respectively).
to complete the operation (for O(state=present) and O(state=absent) respectively).
type: bool
default: false
snapshot_source:
@ -60,11 +60,11 @@ options:
snapshot_conflict:
description:
- Policy defining behavior when a subvolume already exists at the path of the requested snapshot.
- C(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required.
- V(skip) - Create a snapshot only if a subvolume does not yet exist at the target location, otherwise indicate that no change is required.
Warning, this option does not yet verify that the target subvolume was generated from a snapshot of the requested source.
- C(clobber) - If a subvolume already exists at the requested location, delete it first.
- V(clobber) - If a subvolume already exists at the requested location, delete it first.
This option is not idempotent and will result in a new snapshot being generated on every execution.
- C(error) - If a subvolume already exists at the requested location, return an error.
- V(error) - If a subvolume already exists at the requested location, return an error.
This option is not idempotent and will result in an error on replay of the module.
type: str
choices: [ skip, clobber, error ]
@ -77,7 +77,7 @@ options:
default: present
notes:
- If any or all of the options I(filesystem_device), I(filesystem_label) or I(filesystem_uuid) parameters are provided, there is expected
- If any or all of the options O(filesystem_device), O(filesystem_label) or O(filesystem_uuid) parameters are provided, there is expected
to be a matching btrfs filesystem. If none are provided and only a single btrfs filesystem exists or only a single
btrfs filesystem is mounted, that filesystem will be used; otherwise, the module will take no action and return an error.
@ -201,7 +201,7 @@ modifications:
target_subvolume_id:
description:
- The ID of the subvolume specified with the I(name) parameter, either pre-existing or created as part of module execution.
- The ID of the subvolume specified with the O(name) parameter, either pre-existing or created as part of module execution.
type: int
sample: 257
returned: Success and subvolume exists after module execution

8
plugins/modules/bzr.py
View file

@ -16,7 +16,7 @@ author:
- André Paramés (@andreparames)
short_description: Deploy software (or files) from bzr branches
description:
- Manage I(bzr) branches to deploy files or software.
- Manage C(bzr) branches to deploy files or software.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -44,9 +44,9 @@ options:
type: str
force:
description:
- If C(true), any modified files in the working
tree will be discarded. Before 1.9 the default
value was C(true).
- If V(true), any modified files in the working
tree will be discarded. Before Ansible 1.9 the default
value was V(true).
type: bool
default: false
executable:

4
plugins/modules/cargo.py
View file

@ -35,12 +35,12 @@ options:
description:
->
The base path where to install the Rust packages. Cargo automatically appends
C(/bin). In other words, C(/usr/local) will become C(/usr/local/bin).
V(/bin). In other words, V(/usr/local) will become V(/usr/local/bin).
type: path
version:
description:
->
The version to install. If I(name) contains multiple values, the module will
The version to install. If O(name) contains multiple values, the module will
try to install all of them in this version.
type: str
required: false

4
plugins/modules/circonus_annotation.py
View file

@ -52,12 +52,12 @@ options:
type: int
description:
- Unix timestamp of event start
- If not specified, it defaults to I(now).
- If not specified, it defaults to "now".
stop:
type: int
description:
- Unix timestamp of event end
- If not specified, it defaults to I(now) + I(duration).
- If not specified, it defaults to "now" + O(duration).
duration:
type: int
description:

34
plugins/modules/cloudflare_dns.py
View file

@ -31,7 +31,7 @@ options:
- API token.
- Required for api token authentication.
- "You can obtain your API token from the bottom of the Cloudflare 'My Account' page, found here: U(https://dash.cloudflare.com/)."
- Can be specified in C(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0.
- Can be specified in E(CLOUDFLARE_TOKEN) environment variable since community.general 2.0.0.
type: str
required: false
version_added: '0.2.0'
@ -51,39 +51,39 @@ options:
algorithm:
description:
- Algorithm number.
- Required for I(type=DS) and I(type=SSHFP) when I(state=present).
- Required for O(type=DS) and O(type=SSHFP) when O(state=present).
type: int
cert_usage:
description:
- Certificate usage number.
- Required for I(type=TLSA) when I(state=present).
- Required for O(type=TLSA) when O(state=present).
type: int
choices: [ 0, 1, 2, 3 ]
hash_type:
description:
- Hash type number.
- Required for I(type=DS), I(type=SSHFP) and I(type=TLSA) when I(state=present).
- Required for O(type=DS), O(type=SSHFP) and O(type=TLSA) when O(state=present).
type: int
choices: [ 1, 2 ]
key_tag:
description:
- DNSSEC key tag.
- Needed for I(type=DS) when I(state=present).
- Needed for O(type=DS) when O(state=present).
type: int
port:
description:
- Service port.
- Required for I(type=SRV) and I(type=TLSA).
- Required for O(type=SRV) and O(type=TLSA).
type: int
priority:
description:
- Record priority.
- Required for I(type=MX) and I(type=SRV)
- Required for O(type=MX) and O(type=SRV)
default: 1
type: int
proto:
description:
- Service protocol. Required for I(type=SRV) and I(type=TLSA).
- Service protocol. Required for O(type=SRV) and O(type=TLSA).
- Common values are TCP and UDP.
- Before Ansible 2.6 only TCP and UDP were available.
type: str
@ -95,26 +95,26 @@ options:
record:
description:
- Record to add.
- Required if I(state=present).
- Default is C(@) (e.g. the zone name).
- Required if O(state=present).
- Default is V(@) (that is, the zone name).
type: str
default: '@'
aliases: [ name ]
selector:
description:
- Selector number.
- Required for I(type=TLSA) when I(state=present).
- Required for O(type=TLSA) when O(state=present).
choices: [ 0, 1 ]
type: int
service:
description:
- Record service.
- Required for I(type=SRV).
- Required for O(type=SRV).
type: str
solo:
description:
- Whether the record should be the only one for that record type and record name.
- Only use with I(state=present).
- Only use with O(state=present).
- This will delete all other records with the same record name and type.
type: bool
state:
@ -136,20 +136,20 @@ options:
default: 1
type:
description:
- The type of DNS record to create. Required if I(state=present).
- I(type=DS), I(type=SSHFP) and I(type=TLSA) added in Ansible 2.7.
- The type of DNS record to create. Required if O(state=present).
- O(type=DS), O(type=SSHFP), and O(type=TLSA) were added in Ansible 2.7.
type: str
choices: [ A, AAAA, CNAME, DS, MX, NS, SPF, SRV, SSHFP, TLSA, TXT ]
value:
description:
- The record value.
- Required for I(state=present).
- Required for O(state=present).
type: str
aliases: [ content ]
weight:
description:
- Service weight.
- Required for I(type=SRV).
- Required for O(type=SRV).
type: int
default: 1
zone:

12
plugins/modules/cobbler_system.py
View file

@ -30,7 +30,7 @@ options:
port:
description:
- Port number to be used for REST connection.
- The default value depends on parameter C(use_ssl).
- The default value depends on parameter I(use_ssl).
type: int
username:
description:
@ -43,13 +43,13 @@ options:
type: str
use_ssl:
description:
- If C(false), an HTTP connection will be used instead of the default HTTPS connection.
- If V(false), an HTTP connection will be used instead of the default HTTPS connection.
type: bool
default: true
validate_certs:
description:
- If C(false), SSL certificates will not be validated.
- This should only set to C(false) when used on personally controlled sites using self-signed certificates.
- If V(false), SSL certificates will not be validated.
- This should only set to V(false) when used on personally controlled sites using self-signed certificates.
type: bool
default: true
name:
@ -144,11 +144,11 @@ EXAMPLES = r'''
RETURN = r'''
systems:
description: List of systems
returned: I(state=query) and I(name) is not provided
returned: O(state=query) and O(name) is not provided
type: list
system:
description: (Resulting) information about the system we are working with
returned: when I(name) is provided
returned: when O(name) is provided
type: dict
'''

4
plugins/modules/composer.py
View file

@ -49,7 +49,7 @@ options:
description:
- Directory of your project (see --working-dir). This is required when
the command is not run globally.
- Will be ignored if I(global_command=true).
- Will be ignored if O(global_command=true).
global_command:
description:
- Runs the specified command globally.
@ -111,7 +111,7 @@ options:
version_added: 3.2.0
requirements:
- php
- composer installed in bin path (recommended /usr/local/bin) or specified in I(composer_executable)
- composer installed in bin path (recommended /usr/local/bin) or specified in O(composer_executable)
notes:
- Default options that are always appended in each execution are --no-ansi, --no-interaction and --no-progress if available.
- We received reports about issues on macOS if composer was installed by Homebrew. Please use the official install method to avoid issues.

46
plugins/modules/consul.py
View file

@ -21,8 +21,8 @@ description:
notify the health of the entire node to the cluster.
Service level checks do not require a check name or id as these are derived
by Consul from the Service name and id respectively by appending 'service:'
Node level checks require a I(check_name) and optionally a I(check_id)."
- Currently, there is no complete way to retrieve the script, interval or ttl
Node level checks require a O(check_name) and optionally a O(check_id)."
- Currently, there is no complete way to retrieve the script, interval or TTL
metadata for a registered check. Without this metadata it is not possible to
tell if the data supplied with ansible represents a change to a check. As a
result this does not attempt to determine changes and will always report a
@ -56,7 +56,7 @@ options:
service_id:
type: str
description:
- The ID for the service, must be unique per node. If I(state=absent),
- The ID for the service, must be unique per node. If O(state=absent),
defaults to the service name if supplied.
host:
type: str
@ -86,12 +86,12 @@ options:
type: int
description:
- The port on which the service is listening. Can optionally be supplied for
registration of a service, i.e. if I(service_name) or I(service_id) is set.
registration of a service, that is if O(service_name) or O(service_id) is set.
service_address:
type: str
description:
- The address to advertise that the service will be listening on.
This value will be passed as the I(address) parameter to Consul's
This value will be passed as the C(address) parameter to Consul's
C(/v1/agent/service/register) API method, so refer to the Consul API
documentation for further details.
tags:
@ -103,19 +103,19 @@ options:
type: str
description:
- The script/command that will be run periodically to check the health of the service.
- Requires I(interval) to be provided.
- Requires O(interval) to be provided.
interval:
type: str
description:
- The interval at which the service check will be run.
This is a number with a C(s) or C(m) suffix to signify the units of seconds or minutes e.g C(15s) or C(1m).
If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s).
- Required if one of the parameters I(script), I(http), or I(tcp) is specified.
This is a number with a V(s) or V(m) suffix to signify the units of seconds or minutes, for example V(15s) or V(1m).
If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
- Required if one of the parameters O(script), O(http), or O(tcp) is specified.
check_id:
type: str
description:
- An ID for the service check. If I(state=absent), defaults to
I(check_name). Ignored if part of a service definition.
- An ID for the service check. If O(state=absent), defaults to
O(check_name). Ignored if part of a service definition.
check_name:
type: str
description:
@ -124,34 +124,34 @@ options:
ttl:
type: str
description:
- Checks can be registered with a ttl instead of a I(script) and I(interval)
- Checks can be registered with a TTL instead of a O(script) and O(interval)
this means that the service will check in with the agent before the
ttl expires. If it doesn't the check will be considered failed.
TTL expires. If it doesn't the check will be considered failed.
Required if registering a check and the script an interval are missing
Similar to the interval this is a number with a C(s) or C(m) suffix to
signify the units of seconds or minutes e.g C(15s) or C(1m).
If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s).
Similar to the interval this is a number with a V(s) or V(m) suffix to
signify the units of seconds or minutes, for example V(15s) or V(1m).
If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
tcp:
type: str
description:
- Checks can be registered with a TCP port. This means that consul
will check if the connection attempt to that port is successful (that is, the port is currently accepting connections).
The format is C(host:port), for example C(localhost:80).
- Requires I(interval) to be provided.
The format is V(host:port), for example V(localhost:80).
- Requires O(interval) to be provided.
version_added: '1.3.0'
http:
type: str
description:
- Checks can be registered with an HTTP endpoint. This means that consul
will check that the http endpoint returns a successful HTTP status.
- Requires I(interval) to be provided.
- Requires O(interval) to be provided.
timeout:
type: str
description:
- A custom HTTP check timeout. The consul default is 10 seconds.
Similar to the interval this is a number with a C(s) or C(m) suffix to
signify the units of seconds or minutes, e.g. C(15s) or C(1m).
If no suffix is supplied C(s) will be used by default, e.g. C(10) will be C(10s).
Similar to the interval this is a number with a V(s) or V(m) suffix to
signify the units of seconds or minutes, for example V(15s) or V(1m).
If no suffix is supplied V(s) will be used by default, for example V(10) will be V(10s).
token:
type: str
description:
@ -159,7 +159,7 @@ options:
ack_params_state_absent:
type: bool
description:
- Disable deprecation warning when using parameters incompatible with I(state=absent).
- Disable deprecation warning when using parameters incompatible with O(state=absent).
'''
EXAMPLES = '''

2
plugins/modules/consul_acl.py
View file

@ -156,7 +156,7 @@ token:
rules:
description: the HCL JSON representation of the rules associated to the ACL, in the format described in the
Consul documentation (https://www.consul.io/docs/guides/acl.html#rule-specification).
returned: I(status) == "present"
returned: when O(state=present)
type: dict
sample: {
"key": {

28
plugins/modules/consul_kv.py
View file

@ -17,7 +17,7 @@ description:
- Allows the retrieval, addition, modification and deletion of key/value entries in a
consul cluster via the agent. The entire contents of the record, including
the indices, flags and session are returned as C(value).
- If the C(key) represents a prefix then note that when a value is removed, the existing
- If the O(key) represents a prefix then note that when a value is removed, the existing
value if any is returned as part of the results.
- See http://www.consul.io/docs/agent/http.html#kv for more details.
requirements:
@ -36,14 +36,14 @@ attributes:
options:
state:
description:
- The action to take with the supplied key and value. If the state is C(present) and I(value) is set, the key
contents will be set to the value supplied and C(changed) will be set to C(true) only if the value was
different to the current contents. If the state is C(present) and I(value) is not set, the existing value
associated to the key will be returned. The state C(absent) will remove the key/value pair,
again C(changed) will be set to true only if the key actually existed
- The action to take with the supplied key and value. If the state is V(present) and O(value) is set, the key
contents will be set to the value supplied and C(changed) will be set to V(true) only if the value was
different to the current contents. If the state is V(present) and O(value) is not set, the existing value
associated to the key will be returned. The state V(absent) will remove the key/value pair,
again C(changed) will be set to V(true) only if the key actually existed
prior to the removal. An attempt can be made to obtain or free the
lock associated with a key/value pair with the states C(acquire) or
C(release) respectively. a valid session must be supplied to make the
lock associated with a key/value pair with the states V(acquire) or
V(release) respectively. a valid session must be supplied to make the
attempt changed will be true if the attempt is successful, false
otherwise.
type: str
@ -56,17 +56,17 @@ options:
required: true
value:
description:
- The value should be associated with the given key, required if C(state)
is C(present).
- The value should be associated with the given key, required if O(state)
is V(present).
type: str
recurse:
description:
- If the key represents a prefix, each entry with the prefix can be
retrieved by setting this to C(true).
retrieved by setting this to V(true).
type: bool
retrieve:
description:
- If the I(state) is C(present) and I(value) is set, perform a
- If the O(state) is V(present) and O(value) is set, perform a
read after setting the value and return this value.
default: true
type: bool
@ -82,9 +82,9 @@ options:
type: str
cas:
description:
- Used when acquiring a lock with a session. If the C(cas) is C(0), then
- Used when acquiring a lock with a session. If the O(cas) is V(0), then
Consul will only put the key if it does not already exist. If the
C(cas) value is non-zero, then the key is only set if the index matches
O(cas) value is non-zero, then the key is only set if the index matches
the ModifyIndex of that key.
type: str
flags:

14
plugins/modules/consul_session.py
View file

@ -31,25 +31,25 @@ attributes:
options:
id:
description:
- ID of the session, required when I(state) is either C(info) or
C(remove).
- ID of the session, required when O(state) is either V(info) or
V(remove).
type: str
state:
description:
- Whether the session should be present i.e. created if it doesn't
exist, or absent, removed if present. If created, the I(id) for the
session is returned in the output. If C(absent), I(id) is
exist, or absent, removed if present. If created, the O(id) for the
session is returned in the output. If V(absent), O(id) is
required to remove the session. Info for a single session, all the
sessions for a node or all available sessions can be retrieved by
specifying C(info), C(node) or C(list) for the I(state); for C(node)
or C(info), the node I(name) or session I(id) is required as parameter.
specifying V(info), V(node) or V(list) for the O(state); for V(node)
or V(info), the node O(name) or session O(id) is required as parameter.
choices: [ absent, info, list, node, present ]
type: str
default: present
name:
description:
- The name that should be associated with the session. Required when
I(state=node) is used.
O(state=node) is used.
type: str
delay:
description:

32
plugins/modules/cpanm.py
View file

@ -27,8 +27,8 @@ options:
name:
type: str
description:
- The Perl library to install. Valid values change according to the I(mode), see notes for more details.
- Note that for installing from a local path the parameter I(from_path) should be used.
- The Perl library to install. Valid values change according to the O(mode), see notes for more details.
- Note that for installing from a local path the parameter O(from_path) should be used.
aliases: [pkg]
from_path:
type: path
@ -59,7 +59,7 @@ options:
default: false
version:
description:
- Version specification for the perl module. When I(mode) is C(new), C(cpanm) version operators are accepted.
- Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted.
type: str
executable:
description:
@ -68,32 +68,24 @@ options:
mode:
description:
- Controls the module behavior. See notes below for more details.
- Default is C(compatibility) but that behavior is deprecated and will be changed to C(new) in community.general 9.0.0.
- Default is V(compatibility) but that behavior is deprecated and will be changed to V(new) in community.general 9.0.0.
type: str
choices: [compatibility, new]
version_added: 3.0.0
name_check:
description:
- When in C(new) mode, this parameter can be used to check if there is a module I(name) installed (at I(version), when specified).
- When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified).
type: str
version_added: 3.0.0
notes:
- Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host.
- "This module now comes with a choice of execution I(mode): C(compatibility) or C(new)."
- "C(compatibility) mode:"
- When using C(compatibility) mode, the module will keep backward compatibility. This is the default mode.
- I(name) must be either a module name or a distribution file.
- >
If the perl module given by I(name) is installed (at the exact I(version) when specified), then nothing happens.
Otherwise, it will be installed using the C(cpanm) executable.
- I(name) cannot be an URL, or a git URL.
- C(cpanm) version specifiers do not work in this mode.
- "C(new) mode:"
- "When using C(new) mode, the module will behave differently"
- >
The I(name) parameter may refer to a module name, a distribution file,
a HTTP URL or a git repository URL as described in C(cpanminus) documentation.
- C(cpanm) version specifiers are recognized.
- "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)."
- "O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. This is the default mode.
O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version)
when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL.
C(cpanm) version specifiers do not work in this mode."
- "O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file,
a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized."
author:
- "Franck Cuny (@fcuny)"
- "Alexei Znamensky (@russoz)"

13
plugins/modules/cronvar.py
View file

@ -40,16 +40,16 @@ options:
value:
description:
- The value to set this variable to.
- Required if I(state=present).
- Required if O(state=present).
type: str
insertafter:
description:
- If specified, the variable will be inserted after the variable specified.
- Used with I(state=present).
- Used with O(state=present).
type: str
insertbefore:
description:
- Used with I(state=present). If specified, the variable will be inserted
- Used with O(state=present). If specified, the variable will be inserted
just before the variable specified.
type: str
state:
@ -61,18 +61,19 @@ options:
user:
description:
- The specific user whose crontab should be modified.
- This parameter defaults to C(root) when unset.
- This parameter defaults to V(root) when unset.
type: str
cron_file:
description:
- If specified, uses this file instead of an individual user's crontab.
- Without a leading C(/), this is assumed to be in I(/etc/cron.d).
- With a leading C(/), this is taken as absolute.
- Without a leading V(/), this is assumed to be in C(/etc/cron.d).
- With a leading V(/), this is taken as absolute.
type: str
backup:
description:
- If set, create a backup of the crontab before it is modified.
The location of the backup is returned in the C(backup) variable by this module.
# TODO: C() above should be RV(), but return values have not been documented!
type: bool
default: false
requirements:

20
plugins/modules/crypttab.py
View file

@ -25,38 +25,38 @@ options:
name:
description:
- Name of the encrypted block device as it appears in the C(/etc/crypttab) file, or
optionally prefixed with C(/dev/mapper/), as it appears in the filesystem. I(/dev/mapper/)
will be stripped from I(name).
optionally prefixed with V(/dev/mapper/), as it appears in the filesystem. V(/dev/mapper/)
will be stripped from O(name).
type: str
required: true
state:
description:
- Use I(present) to add a line to C(/etc/crypttab) or update its definition
- Use V(present) to add a line to C(/etc/crypttab) or update its definition
if already present.
- Use I(absent) to remove a line with matching I(name).
- Use I(opts_present) to add options to those already present; options with
- Use V(absent) to remove a line with matching O(name).
- Use V(opts_present) to add options to those already present; options with
different values will be updated.
- Use I(opts_absent) to remove options from the existing set.
- Use V(opts_absent) to remove options from the existing set.
type: str
required: true
choices: [ absent, opts_absent, opts_present, present ]
backing_device:
description:
- Path to the underlying block device or file, or the UUID of a block-device
prefixed with I(UUID=).
prefixed with V(UUID=).
type: str
password:
description:
- Encryption password, the path to a file containing the password, or
C(-) or unset if the password should be entered at boot.
V(-) or unset if the password should be entered at boot.
type: path
opts:
description:
- A comma-delimited list of options. See C(crypttab(5) ) for details.
- A comma-delimited list of options. See V(crypttab(5\)) for details.
type: str
path:
description:
- Path to file to use instead of C(/etc/crypttab).
- Path to file to use instead of V(/etc/crypttab).
- This might be useful in a chroot environment.
type: path
default: /etc/crypttab