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

Use semantic markup (modules d-g) (#6672)

Browse source 
* Use semantic markup.

* 'ignore:' is no longer needed.

* E() now works better.
This commit is contained in:
Felix Fontein 2023-06-15 15:46:44 +02:00 committed by GitHub
parent 6fc1df9b83
commit 2ed82e0318
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
34 changed files with 307 additions and 306 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
plugins/modules/datadog_monitor.py
View file

@ -16,7 +16,6 @@ short_description: Manages Datadog monitors
description:
- Manages monitors within Datadog.
- Options as described on https://docs.datadoghq.com/api/.
- The type C(event-v2) was added in community.general 4.8.0.
author: Sebastian Kornehl (@skornehl)
requirements: [datadog]
extends_documentation_fragment:
@ -34,8 +33,8 @@ options:
type: str
api_host:
description:
- The URL to the Datadog API. Default value is C(https://api.datadoghq.com).
- This value can also be set with the C(DATADOG_HOST) environment variable.
- The URL to the Datadog API. Default value is V(https://api.datadoghq.com).
- This value can also be set with the E(DATADOG_HOST) environment variable.
required: false
type: str
version_added: '0.2.0'
@ -59,8 +58,9 @@ options:
type:
description:
- The type of the monitor.
- The types C(query alert), C(trace-analytics alert) and C(rum alert) were added in community.general 2.1.0.
- The type C(composite) was added in community.general 3.4.0.
- The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0.
- The type V(composite) was added in community.general 3.4.0.
- The type V(event-v2 alert) was added in community.general 4.8.0.
choices:
- metric alert
- service check
@ -117,7 +117,7 @@ options:
escalation_message:
description:
- A message to include with a re-notification. Supports the '@username' notification we allow elsewhere.
- Not applicable if I(renotify_interval=None).
- Not applicable if O(renotify_interval=none).
type: str
notify_audit:
description:
@ -130,7 +130,7 @@ options:
- A dictionary of thresholds by status.
- Only available for service checks and metric alerts.
- Because each of them can have multiple thresholds, we do not define them directly in the query.
- "If not specified, it defaults to: C({'ok': 1, 'critical': 1, 'warning': 1})."
- "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})."
locked:
description:
- Whether changes to this monitor should be restricted to the creator or admins.

47
plugins/modules/deploy_helper.py
View file

@ -20,8 +20,9 @@ description:
- The Deploy Helper manages some of the steps common in deploying software.
It creates a folder structure, manages a symlink for the current release
and cleans up old releases.
- "Running it with the I(state=query) or I(state=present) will return the C(deploy_helper) fact.
C(project_path), whatever you set in the I(path) parameter,
# TODO: convert below to RETURN documentation!
- "Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact.
C(project_path), whatever you set in the O(path) parameter,
C(current_path), the path to the symlink that points to the active release,
C(releases_path), the path to the folder to keep releases in,
C(shared_path), the path to the folder to keep shared resources in,
@ -50,33 +51,33 @@ options:
type: str
description:
- The state of the project.
C(query) will only gather facts,
C(present) will create the project I(root) folder, and in it the I(releases) and I(shared) folders,
C(finalize) will remove the unfinished_filename file, create a symlink to the newly
deployed release and optionally clean old releases,
C(clean) will remove failed & old releases,
C(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with I(state=absent)).
- V(query) will only gather facts.
- V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders.
- V(finalize) will remove the unfinished_filename file, create a symlink to the newly
deployed release and optionally clean old releases.
- V(clean) will remove failed & old releases.
- V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)).
choices: [ present, finalize, absent, clean, query ]
default: present
release:
type: str
description:
- The release version that is being deployed. Defaults to a timestamp format %Y%m%d%H%M%S (i.e. '20141119223359').
This parameter is optional during I(state=present), but needs to be set explicitly for I(state=finalize).
You can use the generated fact I(release={{ deploy_helper.new_release }}).
- The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)).
This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize).
You can use the generated fact C(release={{ deploy_helper.new_release }}).
releases_path:
type: str
description:
- The name of the folder that will hold the releases. This can be relative to I(path) or absolute.
- The name of the folder that will hold the releases. This can be relative to O(path) or absolute.
Returned in the C(deploy_helper.releases_path) fact.
default: releases
shared_path:
type: path
description:
- The name of the folder that will hold the shared resources. This can be relative to I(path) or absolute.
- The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute.
If this is set to an empty string, no shared folder will be created.
Returned in the C(deploy_helper.shared_path) fact.
default: shared
@ -84,38 +85,38 @@ options:
current_path:
type: path
description:
- The name of the symlink that is created when the deploy is finalized. Used in I(finalize) and I(clean).
- The name of the symlink that is created when the deploy is finalized. Used in O(state=finalize) and O(state=clean).
Returned in the C(deploy_helper.current_path) fact.
default: current
unfinished_filename:
type: str
description:
- The name of the file that indicates a deploy has not finished. All folders in the I(releases_path) that
contain this file will be deleted on I(state=finalize) with I(clean=True), or I(state=clean). This file is
automatically deleted from the I(new_release_path) during I(state=finalize).
- The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that
contain this file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is
automatically deleted from the C(new_release_path) during O(state=finalize).
default: DEPLOY_UNFINISHED
clean:
description:
- Whether to run the clean procedure in case of I(state=finalize).
- Whether to run the clean procedure in case of O(state=finalize).
type: bool
default: true
keep_releases:
type: int
description:
- The number of old releases to keep when cleaning. Used in I(finalize) and I(clean). Any unfinished builds
- The number of old releases to keep when cleaning. Used in O(state=finalize) and O(state=clean). Any unfinished builds
will be deleted first, so only correct releases will count. The current version will not count.
default: 5
notes:
- Facts are only returned for I(state=query) and I(state=present). If you use both, you should pass any overridden
- Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden
parameters to both calls, otherwise the second call will overwrite the facts of the first one.
- When using I(state=clean), the releases are ordered by I(creation date). You should be able to switch to a
- When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a
new naming strategy without problems.
- Because of the default behaviour of generating the I(new_release) fact, this module will not be idempotent
unless you pass your own release name with I(release). Due to the nature of deploying software, this should not
- Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent
unless you pass your own release name with O(release). Due to the nature of deploying software, this should not
be much of a problem.
extends_documentation_fragment:
- ansible.builtin.files

2
plugins/modules/dimensiondata_network.py
View file

@ -84,7 +84,7 @@ EXAMPLES = '''
RETURN = '''
network:
description: Dictionary describing the network.
returned: On success when I(state=present).
returned: On success when O(state=present).
type: complex
contains:
id:

8
plugins/modules/dimensiondata_vlan.py
View file

@ -51,20 +51,20 @@ options:
private_ipv4_prefix_size:
description:
- The size of the IPv4 address space, e.g 24.
- Required, if C(private_ipv4_base_address) is specified.
- Required, if O(private_ipv4_base_address) is specified.
type: int
default: 0
state:
description:
- The desired state for the target VLAN.
- C(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist).
- V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist).
choices: [present, absent, readonly]
default: present
type: str
allow_expand:
description:
- Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses.
- If C(False), the module will fail under these conditions.
- If V(false), the module will fail under these conditions.
- This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible).
type: bool
default: false
@ -105,7 +105,7 @@ EXAMPLES = '''
RETURN = '''
vlan:
description: Dictionary describing the VLAN.
returned: On success when I(state) is 'present'
returned: On success when O(state=present)
type: complex
contains:
id:

6
plugins/modules/discord.py
View file

@ -43,7 +43,7 @@ options:
content:
description:
- Content of the message to the Discord channel.
- At least one of I(content) and I(embeds) must be specified.
- At least one of O(content) and O(embeds) must be specified.
type: str
username:
description:
@ -55,7 +55,7 @@ options:
type: str
tts:
description:
- Set this to C(true) if this is a TTS (Text to Speech) message.
- Set this to V(true) if this is a TTS (Text to Speech) message.
type: bool
default: false
embeds:
@ -63,7 +63,7 @@ options:
- Send messages as Embeds to the Discord channel.
- Embeds can have a colored border, embedded images, text fields and more.
- "Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object)"
- At least one of I(content) and I(embeds) must be specified.
- At least one of O(content) and O(embeds) must be specified.
type: list
elements: dict
'''

70
plugins/modules/django_manage.py
View file

@ -16,7 +16,7 @@ module: django_manage
short_description: Manages a Django application
description:
- Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the
I(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation.
O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -29,20 +29,20 @@ options:
description:
- The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation.
- >
C(cleanup) - clean up old data from the database (deprecated in Django 1.5). This parameter will be
removed in community.general 9.0.0. Use C(clearsessions) instead.
- C(collectstatic) - Collects the static files into C(STATIC_ROOT).
- C(createcachetable) - Creates the cache tables for use with the database cache backend.
- C(flush) - Removes all data from the database.
- C(loaddata) - Searches for and loads the contents of the named I(fixtures) into the database.
- C(migrate) - Synchronizes the database state with models and migrations.
V(cleanup) - clean up old data from the database (deprecated in Django 1.5). This parameter will be
removed in community.general 9.0.0. Use V(clearsessions) instead.
- V(collectstatic) - Collects the static files into C(STATIC_ROOT).
- V(createcachetable) - Creates the cache tables for use with the database cache backend.
- V(flush) - Removes all data from the database.
- V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database.
- V(migrate) - Synchronizes the database state with models and migrations.
- >
C(syncdb) - Synchronizes the database state with models and migrations (deprecated in Django 1.7).
This parameter will be removed in community.general 9.0.0. Use C(migrate) instead.
- C(test) - Runs tests for all installed apps.
V(syncdb) - Synchronizes the database state with models and migrations (deprecated in Django 1.7).
This parameter will be removed in community.general 9.0.0. Use V(migrate) instead.
- V(test) - Runs tests for all installed apps.
- >
C(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be
removed in community.general 9.0.0. Use C(check) instead.
V(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be
removed in community.general 9.0.0. Use V(check) instead.
- Other commands can be entered, but will fail if they are unknown to Django. Other commands that may
prompt for user input should be run with the C(--noinput) flag.
type: str
@ -55,14 +55,14 @@ options:
aliases: [app_path, chdir]
settings:
description:
- The Python path to the application's settings module, such as C(myapp.settings).
- The Python path to the application's settings module, such as V(myapp.settings).
type: path
required: false
pythonpath:
description:
- A directory to add to the Python path. Typically used to include the settings module if it is located
external to the application directory.
- This would be equivalent to adding I(pythonpath)'s value to the C(PYTHONPATH) environment variable.
- This would be equivalent to adding O(pythonpath)'s value to the C(PYTHONPATH) environment variable.
type: path
required: false
aliases: [python_path]
@ -73,54 +73,54 @@ options:
aliases: [virtual_env]
apps:
description:
- A list of space-delimited apps to target. Used by the C(test) command.
- A list of space-delimited apps to target. Used by the V(test) command.
type: str
required: false
cache_table:
description:
- The name of the table used for database-backed caching. Used by the C(createcachetable) command.
- The name of the table used for database-backed caching. Used by the V(createcachetable) command.
type: str
required: false
clear:
description:
- Clear the existing files before trying to copy or link the original file.
- Used only with the C(collectstatic) command. The C(--noinput) argument will be added automatically.
- Used only with the V(collectstatic) command. The C(--noinput) argument will be added automatically.
required: false
default: false
type: bool
database:
description:
- The database to target. Used by the C(createcachetable), C(flush), C(loaddata), C(syncdb),
and C(migrate) commands.
- The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb),
and V(migrate) commands.
type: str
required: false
failfast:
description:
- Fail the command immediately if a test fails. Used by the C(test) command.
- Fail the command immediately if a test fails. Used by the V(test) command.
required: false
default: false
type: bool
aliases: [fail_fast]
fixtures:
description:
- A space-delimited list of fixture file names to load in the database. B(Required) by the C(loaddata) command.
- A space-delimited list of fixture file names to load in the database. B(Required) by the V(loaddata) command.
type: str
required: false
skip:
description:
- Will skip over out-of-order missing migrations, you can only use this parameter with C(migrate) command.
- Will skip over out-of-order missing migrations, you can only use this parameter with V(migrate) command.
required: false
type: bool
merge:
description:
- Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this
parameter with C(migrate) command.
parameter with V(migrate) command.
required: false
type: bool
link:
description:
- Will create links to the files instead of copying them, you can only use this parameter with
C(collectstatic) command.
V(collectstatic) command.
required: false
type: bool
testrunner:
@ -133,9 +133,9 @@ options:
ack_venv_creation_deprecation:
description:
- >-
When a I(virtualenv) is set but the virtual environment does not exist, the current behavior is
When a O(virtualenv) is set but the virtual environment does not exist, the current behavior is
to create a new virtual environment. That behavior is deprecated and if that case happens it will
generate a deprecation warning. Set this flag to C(true) to suppress the deprecation warning.
generate a deprecation warning. Set this flag to V(true) to suppress the deprecation warning.
- Please note that you will receive no further warning about this being removed until the module
will start failing in such cases from community.general 9.0.0 on.
type: bool
@ -146,19 +146,19 @@ notes:
B(ATTENTION - DEPRECATION): Support for Django releases older than 4.1 will be removed in
community.general version 9.0.0 (estimated to be released in May 2024).
Please notice that Django 4.1 requires Python 3.8 or greater.
- C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the I(virtualenv) parameter
- C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the O(virtualenv) parameter
is specified. This requirement is deprecated and will be removed in community.general version 9.0.0.
- This module will create a virtualenv if the I(virtualenv) parameter is specified and a virtual environment does not already
- This module will create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment does not already
exist at the given location. This behavior is deprecated and will be removed in community.general version 9.0.0.
- The parameter I(virtualenv) will remain in use, but it will require the specified virtualenv to exist.
- The parameter O(virtualenv) will remain in use, but it will require the specified virtualenv to exist.
The recommended way to create one in Ansible is by using M(ansible.builtin.pip).
- This module assumes English error messages for the C(createcachetable) command to detect table existence,
- This module assumes English error messages for the V(createcachetable) command to detect table existence,
unfortunately.
- To be able to use the C(migrate) command with django versions < 1.7, you must have C(south) installed and added
- To be able to use the V(migrate) command with django versions < 1.7, you must have C(south) installed and added
as an app in your settings.
- To be able to use the C(collectstatic) command, you must have enabled staticfiles in your settings.
- Your C(manage.py) application must be executable (rwxr-xr-x), and must have a valid shebang,
i.e. C(#!/usr/bin/env python), for invoking the appropriate Python interpreter.
- To be able to use the V(collectstatic) command, you must have enabled staticfiles in your settings.
- Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang,
for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter.
seealso:
- name: django-admin and manage.py Reference
description: Reference for C(django-admin) or C(manage.py) commands.

16
plugins/modules/dnf_versionlock.py
View file

@ -38,7 +38,7 @@ options:
description:
- Package name spec to add or exclude to or delete from the C(locklist)
using the format expected by the C(dnf repoquery) command.
- This parameter is mutually exclusive with I(state=clean).
- This parameter is mutually exclusive with O(state=clean).
type: list
required: false
elements: str
@ -52,19 +52,19 @@ options:
default: false
state:
description:
- Whether to add (C(present) or C(excluded)) to or remove (C(absent) or
C(clean)) from the C(locklist).
- C(present) will add a package name spec to the C(locklist). If there is a
- Whether to add (V(present) or V(excluded)) to or remove (V(absent) or
V(clean)) from the C(locklist).
- V(present) will add a package name spec to the C(locklist). If there is a
installed package that matches, then only that version will be added.
Otherwise, all available package versions will be added.
- C(excluded) will add a package name spec as excluded to the
- V(excluded) will add a package name spec as excluded to the
C(locklist). It means that packages represented by the package name
spec will be excluded from transaction operations. All available
package versions will be added.
- C(absent) will delete entries in the C(locklist) that match the
- V(absent) will delete entries in the C(locklist) that match the
package name spec.
- C(clean) will delete all entries in the C(locklist). This option is
mutually exclusive with C(name).
- V(clean) will delete all entries in the C(locklist). This option is
mutually exclusive with O(name).
choices: [ 'absent', 'clean', 'excluded', 'present' ]
type: str
default: present

4
plugins/modules/dnsimple.py
View file

@ -32,7 +32,7 @@ options:
type: str
account_api_token:
description:
- Account API token. See I(account_email) for more information.
- Account API token. See O(account_email) for more information.
type: str
domain:
description:
@ -77,7 +77,7 @@ options:
solo:
description:
- Whether the record should be the only one for that record type and record name.
- Only use with C(state) is set to C(present) on a record.
- Only use with O(state) is set to V(present) on a record.
type: 'bool'
default: false
sandbox:

6
plugins/modules/dnsimple_info.py
View file

@ -83,7 +83,7 @@ dnsimple_domain_info:
description: Returns a list of dictionaries of all domains associated with the supplied account ID.
type: list
elements: dict
returned: success when I(name) is not specified
returned: success when O(name) is not specified
sample:
- account_id: 1234
created_at: '2021-10-16T21:25:42Z'
@ -120,7 +120,7 @@ dnsimple_records_info:
description: Returns a list of dictionaries with all records for the domain supplied.
type: list
elements: dict
returned: success when I(name) is specified, but I(record) is not
returned: success when O(name) is specified, but O(record) is not
sample:
- content: ns1.dnsimple.com admin.dnsimple.com
created_at: '2021-10-16T19:07:34Z'
@ -174,7 +174,7 @@ dnsimple_records_info:
type: str
dnsimple_record_info:
description: Returns a list of dictionaries that match the record supplied.
returned: success when I(name) and I(record) are specified
returned: success when O(name) and O(record) are specified
type: list
elements: dict
sample:

26
plugins/modules/dpkg_divert.py
View file

@ -20,13 +20,13 @@ description:
- A diversion is for C(dpkg) the knowledge that only a given package
(or the local administrator) is allowed to install a file at a given
location. Other packages shipping their own version of this file will
be forced to I(divert) it, i.e. to install it at another location. It
be forced to O(divert) it, that is to install it at another location. It
allows one to keep changes in a file provided by a debian package by
preventing its overwrite at package upgrade.
- This module manages diversions of debian packages files using the
C(dpkg-divert) commandline tool. It can either create or remove a
diversion for a given file, but also update an existing diversion
to modify its I(holder) and/or its I(divert) location.
to modify its O(holder) and/or its O(divert) location.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -39,14 +39,14 @@ options:
description:
- The original and absolute path of the file to be diverted or
undiverted. This path is unique, i.e. it is not possible to get
two diversions for the same I(path).
two diversions for the same O(path).
required: true
type: path
state:
description:
- When I(state=absent), remove the diversion of the specified
I(path); when I(state=present), create the diversion if it does
not exist, or update its package I(holder) or I(divert) location,
- When O(state=absent), remove the diversion of the specified
O(path); when O(state=present), create the diversion if it does
not exist, or update its package O(holder) or O(divert) location,
if it already exists.
type: str
default: present
@ -59,31 +59,31 @@ options:
- The actual package does not have to be installed or even to exist
for its name to be valid. If not specified, the diversion is hold
by 'LOCAL', that is reserved by/for dpkg for local diversions.
- This parameter is ignored when I(state=absent).
- This parameter is ignored when O(state=absent).
type: str
divert:
description:
- The location where the versions of file will be diverted.
- Default is to add suffix C(.distrib) to the file path.
- This parameter is ignored when I(state=absent).
- This parameter is ignored when O(state=absent).
type: path
rename:
description:
- Actually move the file aside (when I(state=present)) or back (when
I(state=absent)), but only when changing the state of the diversion.
- Actually move the file aside (when O(state=present)) or back (when
O(state=absent)), but only when changing the state of the diversion.
This parameter has no effect when attempting to add a diversion that
already exists or when removing an unexisting one.
- Unless I(force=true), renaming fails if the destination file already
- Unless O(force=true), renaming fails if the destination file already
exists (this lock being a dpkg-divert feature, and bypassing it being
a module feature).
type: bool
default: false
force:
description:
- When I(rename=true) and I(force=true), renaming is performed even if
- When O(rename=true) and O(force=true), renaming is performed even if
the target of the renaming exists, i.e. the existing contents of the
file at this location will be lost.
- This parameter is ignored when I(rename=false).
- This parameter is ignored when O(rename=false).
type: bool
default: false
requirements:

18
plugins/modules/easy_install.py
View file

@ -14,7 +14,7 @@ DOCUMENTATION = '''
module: easy_install
short_description: Installs Python libraries
description:
- Installs Python libraries, optionally in a I(virtualenv)
- Installs Python libraries, optionally in a C(virtualenv)
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -26,13 +26,13 @@ options:
name:
type: str
description:
- A Python library name
- A Python library name.
required: true
virtualenv:
type: str
description:
- an optional I(virtualenv) directory path to install into. If the
I(virtualenv) does not exist, it is created automatically
- An optional O(virtualenv) directory path to install into. If the
O(virtualenv) does not exist, it is created automatically.
virtualenv_site_packages:
description:
- Whether the virtual environment will inherit packages from the
@ -46,21 +46,21 @@ options:
type: str
description:
- The command to create the virtual environment with. For example
C(pyvenv), C(virtualenv), C(virtualenv2).
V(pyvenv), V(virtualenv), V(virtualenv2).
default: virtualenv
executable:
type: str
description:
- The explicit executable or a pathname to the executable to be used to
run easy_install for a specific version of Python installed in the
system. For example C(easy_install-3.3), if there are both Python 2.7
system. For example V(easy_install-3.3), if there are both Python 2.7
and 3.3 installations in the system and you want to run easy_install
for the Python 3.3 installation.
default: easy_install
state:
type: str
description:
- The desired state of the library. C(latest) ensures that the latest version is installed.
- The desired state of the library. V(latest) ensures that the latest version is installed.
choices: [present, latest]
default: present
notes:
@ -68,8 +68,8 @@ notes:
libraries. Thus this module is not able to remove libraries. It is
generally recommended to use the M(ansible.builtin.pip) module which you can first install
using M(community.general.easy_install).
- Also note that I(virtualenv) must be installed on the remote host if the
C(virtualenv) parameter is specified.
- Also note that C(virtualenv) must be installed on the remote host if the
O(virtualenv) parameter is specified.
requirements: [ "virtualenv" ]
author: "Matt Wright (@mattupstate)"
'''

8
plugins/modules/etcd3.py
View file

@ -61,22 +61,22 @@ options:
type: str
description:
- The password to use for authentication.
- Required if I(user) is defined.
- Required if O(user) is defined.
ca_cert:
type: path
description:
- The Certificate Authority to use to verify the etcd host.
- Required if I(client_cert) and I(client_key) are defined.
- Required if O(client_cert) and O(client_key) are defined.
client_cert:
type: path
description:
- PEM formatted certificate chain file to be used for SSL client authentication.
- Required if I(client_key) is defined.
- Required if O(client_key) is defined.
client_key:
type: path
description:
- PEM formatted file that contains your private key to be used for SSL client authentication.
- Required if I(client_cert) is defined.
- Required if O(client_cert) is defined.
timeout:
type: int
description:

2
plugins/modules/facter.py
View file

@ -11,7 +11,7 @@ __metaclass__ = type
DOCUMENTATION = '''
---
module: facter
short_description: Runs the discovery program I(facter) on the remote system
short_description: Runs the discovery program C(facter) on the remote system
description:
- Runs the C(facter) discovery program
(U(https://github.com/puppetlabs/facter)) on the remote system, returning

38
plugins/modules/filesize.py
View file

@ -41,20 +41,20 @@ options:
description:
- Requested size of the file.
- The value is a number (either C(int) or C(float)) optionally followed
by a multiplicative suffix, that can be one of C(B) (bytes), C(KB) or
C(kB) (= 1000B), C(MB) or C(mB) (= 1000kB), C(GB) or C(gB) (= 1000MB),
and so on for C(T), C(P), C(E), C(Z) and C(Y); or alternatively one of
C(K), C(k) or C(KiB) (= 1024B); C(M), C(m) or C(MiB) (= 1024KiB);
C(G), C(g) or C(GiB) (= 1024MiB); and so on.
by a multiplicative suffix, that can be one of V(B) (bytes), V(KB) or
V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB),
and so on for V(T), V(P), V(E), V(Z) and V(Y); or alternatively one of
V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB);
V(G), V(g) or V(GiB) (= 1024MiB); and so on.
- If the multiplicative suffix is not provided, the value is treated as
an integer number of blocks of I(blocksize) bytes each (float values
an integer number of blocks of O(blocksize) bytes each (float values
are rounded to the closest integer).
- When the I(size) value is equal to the current file size, does nothing.
- When the I(size) value is bigger than the current file size, bytes from
I(source) (if I(sparse) is not C(false)) are appended to the file
- When the O(size) value is equal to the current file size, does nothing.
- When the O(size) value is bigger than the current file size, bytes from
O(source) (if O(sparse) is not V(false)) are appended to the file
without truncating it, in other words, without modifying the existing
bytes of the file.
- When the I(size) value is smaller than the current file size, it is
- When the O(size) value is smaller than the current file size, it is
truncated to the requested value without modifying bytes before this
value.
- That means that a file of any arbitrary size can be grown to any other
@ -65,24 +65,24 @@ options:
blocksize:
description:
- Size of blocks, in bytes if not followed by a multiplicative suffix.
- The numeric value (before the unit) C(MUST) be an integer (or a C(float)
- The numeric value (before the unit) B(MUST) be an integer (or a C(float)
if it equals an integer).
- If not set, the size of blocks is guessed from the OS and commonly
results in C(512) or C(4096) bytes, that is used internally by the
module or when I(size) has no unit.
results in V(512) or V(4096) bytes, that is used internally by the
module or when O(size) has no unit.
type: raw
source:
description:
- Device or file that provides input data to provision the file.
- This parameter is ignored when I(sparse=true).
- This parameter is ignored when O(sparse=true).
type: path
default: /dev/zero
force:
description:
- Whether or not to overwrite the file if it exists, in other words, to
truncate it from 0. When C(true), the module is not idempotent, that
means it always reports I(changed=true).
- I(force=true) and I(sparse=true) are mutually exclusive.
truncate it from 0. When V(true), the module is not idempotent, that
means it always reports C(changed=true).
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
default: false
sparse:
@ -91,7 +91,7 @@ options:
- This option is effective only on newly created files, or when growing a
file, only for the bytes to append.
- This option is not supported on OSes or filesystems not supporting sparse files.
- I(force=true) and I(sparse=true) are mutually exclusive.
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
default: false
unsafe_writes:
@ -206,7 +206,7 @@ filesize:
type: int
sample: 1024
bytes:
description: Size of the file, in bytes, as the product of C(blocks) and C(blocksize).
description: Size of the file, in bytes, as the product of RV(filesize.blocks) and RV(filesize.blocksize).
type: int
sample: 512000
iec:

28
plugins/modules/filesystem.py
View file

@ -29,12 +29,12 @@ attributes:
options:
state:
description:
- If I(state=present), the filesystem is created if it doesn't already
exist, that is the default behaviour if I(state) is omitted.
- If I(state=absent), filesystem signatures on I(dev) are wiped if it
- If O(state=present), the filesystem is created if it doesn't already
exist, that is the default behaviour if O(state) is omitted.
- If O(state=absent), filesystem signatures on O(dev) are wiped if it
contains a filesystem (as known by C(blkid)).
- When I(state=absent), all other options but I(dev) are ignored, and the
module doesn't fail if the device I(dev) doesn't actually exist.
- When O(state=absent), all other options but O(dev) are ignored, and the
module does not fail if the device O(dev) doesn't actually exist.
type: str
choices: [ present, absent ]
default: present
@ -43,7 +43,7 @@ options:
choices: [ btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs ]
description:
- Filesystem type to be created. This option is required with
I(state=present) (or if I(state) is omitted).
O(state=present) (or if O(state) is omitted).
- ufs support has been added in community.general 3.4.0.
type: str
aliases: [type]
@ -53,20 +53,20 @@ options:
regular file (both).
- When setting Linux-specific filesystem types on FreeBSD, this module
only works when applying to regular files, aka disk images.
- Currently C(lvm) (Linux-only) and C(ufs) (FreeBSD-only) don't support
a regular file as their target I(dev).
- Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support
a regular file as their target O(dev).
- Support for character devices on FreeBSD has been added in community.general 3.4.0.
type: path
required: true
aliases: [device]
force:
description:
- If C(true), allows to create new filesystem on devices that already has filesystem.
- If V(true), allows to create new filesystem on devices that already has filesystem.
type: bool
default: false
resizefs:
description:
- If C(true), if the block device and filesystem size differ, grow the filesystem into the space.
- If V(true), if the block device and filesystem size differ, grow the filesystem into the space.
- Supported for C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) filesystems.
Attempts to resize other filesystem types will fail.
- XFS Will only grow if mounted. Currently, the module is based on commands
@ -80,20 +80,20 @@ options:
- List of options to be passed to C(mkfs) command.
type: str
requirements:
- Uses specific tools related to the I(fstype) for creating or resizing a
- Uses specific tools related to the O(fstype) for creating or resizing a
filesystem (from packages e2fsprogs, xfsprogs, dosfstools, and so on).
- Uses generic tools mostly related to the Operating System (Linux or
FreeBSD) or available on both, as C(blkid).
- On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required.
notes:
- Potential filesystems on I(dev) are checked using C(blkid). In case C(blkid)
- Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid)
is unable to detect a filesystem (and in case C(fstyp) on FreeBSD is also
unable to detect a filesystem), this filesystem is overwritten even if
I(force) is C(false).
O(force) is V(false).
- On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide
a C(blkid) command that is compatible with this module. However, these
packages conflict with each other, and only the C(util-linux) package
provides the command required to not fail when I(state=absent).
provides the command required to not fail when O(state=absent).
seealso:
- module: community.general.filesize
- module: ansible.posix.mount

14
plugins/modules/flatpak.py
View file

@ -39,8 +39,8 @@ options:
method:
description:
- The installation method to use.
- Defines if the I(flatpak) is supposed to be installed globally for the whole C(system)
or only for the current C(user).
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system)
or only for the current V(user).
type: str
choices: [ system, user ]
default: system
@ -48,14 +48,14 @@ options:
description:
- The name of the flatpak to manage. To operate on several packages this
can accept a list of packages.
- When used with I(state=present), I(name) can be specified as a URL to a
- When used with O(state=present), O(name) can be specified as a URL to a
C(flatpakref) file or the unique reverse DNS name that identifies a flatpak.
- Both C(https://) and C(http://) URLs are supported.
- When supplying a reverse DNS name, you can use the I(remote) option to specify on what remote
- When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote
to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit).
- When used with I(state=absent), it is recommended to specify the name in the reverse DNS
- When used with O(state=absent), it is recommended to specify the name in the reverse DNS
format.
- When supplying a URL with I(state=absent), the module will try to match the
- When supplying a URL with O(state=absent), the module will try to match the
installed flatpak based on the name of the flatpakref to remove it. However, there is no
guarantee that the names of the flatpakref file and the reverse DNS name of the installed
flatpak do match.
@ -74,7 +74,7 @@ options:
remote:
description:
- The flatpak remote (repository) to install the flatpak from.
- By default, C(flathub) is assumed, but you do need to add the flathub flatpak_remote before
- By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before
you can use this.
- See the M(community.general.flatpak_remote) module for managing flatpak remotes.
type: str

22
plugins/modules/flatpak_remote.py
View file

@ -18,7 +18,7 @@ description:
- Allows users to add or remove flatpak remotes.
- The flatpak remotes concept is comparable to what is called repositories in other packaging
formats.
- Currently, remote addition is only supported via I(flatpakrepo) file URLs.
- Currently, remote addition is only supported via C(flatpakrepo) file URLs.
- Existing remotes will not be updated.
- See the M(community.general.flatpak) module for managing flatpaks.
author:
@ -42,26 +42,26 @@ options:
default: flatpak
flatpakrepo_url:
description:
- The URL to the I(flatpakrepo) file representing the repository remote to add.
- When used with I(state=present), the flatpak remote specified under the I(flatpakrepo_url)
is added using the specified installation C(method).
- When used with I(state=absent), this is not required.
- Required when I(state=present).
- The URL to the C(flatpakrepo) file representing the repository remote to add.
- When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url)
is added using the specified installation O(method).
- When used with O(state=absent), this is not required.
- Required when O(state=present).
type: str
method:
description:
- The installation method to use.
- Defines if the I(flatpak) is supposed to be installed globally for the whole C(system)
or only for the current C(user).
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system)
or only for the current V(user).
type: str
choices: [ system, user ]
default: system
name:
description:
- The desired name for the flatpak remote to be registered under on the managed host.
- When used with I(state=present), the remote will be added to the managed host under
the specified I(name).
- When used with I(state=absent) the remote with that name will be removed.
- When used with O(state=present), the remote will be added to the managed host under
the specified O(name).
- When used with O(state=absent) the remote with that name will be removed.
type: str
required: true
state:

4
plugins/modules/gandi_livedns.py
View file

@ -44,7 +44,7 @@ options:
ttl:
description:
- The TTL to give the new record.
- Required when I(state=present).
- Required when O(state=present).
type: int
type:
description:
@ -54,7 +54,7 @@ options:
values:
description:
- The record values.
- Required when I(state=present).
- Required when O(state=present).
type: list
elements: str
domain:

16
plugins/modules/gconftool2.py
View file

@ -36,18 +36,18 @@ options:
description:
- Preference keys typically have simple values such as strings,
integers, or lists of strings and integers.
This is ignored unless I(state=present). See man gconftool-2(1).
This is ignored unless O(state=present). See man gconftool-2(1).
value_type:
type: str
description:
- The type of value being set.
This is ignored unless I(state=present). See man gconftool-2(1).
This is ignored unless O(state=present). See man gconftool-2(1).
choices: [ bool, float, int, string ]
state:
type: str
description:
- The action to take upon the key/value.
- State C(get) is deprecated and will be removed in community.general 8.0.0. Please use the module M(community.general.gconftool2_info) instead.
- State V(get) is deprecated and will be removed in community.general 8.0.0. Please use the module M(community.general.gconftool2_info) instead.
required: true
choices: [ absent, get, present ]
config_source:
@ -57,8 +57,8 @@ options:
See man gconftool-2(1).
direct:
description:
- Access the config database directly, bypassing server. If I(direct) is
specified then the I(config_source) must be specified as well.
- Access the config database directly, bypassing server. If O(direct) is
specified then the O(config_source) must be specified as well.
See man gconftool-2(1).
type: bool
default: false
@ -85,15 +85,15 @@ RETURN = '''
sample: string
value:
description:
- The value of the preference key after executing the module or C(null) if key is removed.
- From community.general 7.0.0 onwards it returns C(null) for a non-existent I(key), and returns C("") before that.
- The value of the preference key after executing the module or V(null) if key is removed.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
previous_value:
description:
- The value of the preference key before executing the module.
- From community.general 7.0.0 onwards it returns C(null) for a non-existent I(key), and returns C("") before that.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"

20
plugins/modules/git_config.py
View file

@ -20,7 +20,7 @@ author:
requirements: ['git']
short_description: Read and write git configuration
description:
- The C(git_config) module changes git configuration by invoking 'git config'.
- The M(community.general.git_config) module changes git configuration by invoking 'git config'.
This is needed if you do not want to use M(ansible.builtin.template) for the entire git
config file (for example because you need to change just C(user.email) in
/etc/.git/config). Solutions involving M(ansible.builtin.command) are cumbersome or
@ -35,7 +35,7 @@ attributes:
options:
list_all:
description:
- List all settings (optionally limited to a given I(scope)).
- List all settings (optionally limited to a given O(scope)).
type: bool
default: false
name:
@ -50,23 +50,23 @@ options:
type: path
file:
description:
- Path to an adhoc git configuration file to be managed using the C(file) scope.
- Path to an adhoc git configuration file to be managed using the V(file) scope.
type: path
version_added: 2.0.0
scope:
description:
- Specify which scope to read/set values from.
- This is required when setting config values.
- If this is set to C(local), you must also specify the C(repo) parameter.
- If this is set to C(file), you must also specify the C(file) parameter.
- It defaults to system only when not using I(list_all)=C(true).
- If this is set to V(local), you must also specify the O(repo) parameter.
- If this is set to V(file), you must also specify the O(file) parameter.
- It defaults to system only when not using O(list_all=true).
choices: [ "file", "local", "global", "system" ]
type: str
state:
description:
- "Indicates the setting should be set/unset.
This parameter has higher precedence than I(value) parameter:
when I(state)=absent and I(value) is defined, I(value) is discarded."
This parameter has higher precedence than O(value) parameter:
when O(state=absent) and O(value) is defined, O(value) is discarded."
choices: [ 'present', 'absent' ]
default: 'present'
type: str
@ -152,13 +152,13 @@ EXAMPLES = '''
RETURN = '''
---
config_value:
description: When I(list_all=false) and value is not set, a string containing the value of the setting in name
description: When O(list_all=false) and value is not set, a string containing the value of the setting in name
returned: success
type: str
sample: "vim"
config_values:
description: When I(list_all=true), a dict containing key/value pairs of multiple configuration settings
description: When O(list_all=true), a dict containing key/value pairs of multiple configuration settings
returned: success
type: dict
sample:

10
plugins/modules/github_deploy_key.py
View file

@ -58,7 +58,7 @@ options:
type: str
read_only:
description:
- If C(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write.
- If V(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write.
type: bool
default: true
state:
@ -69,7 +69,7 @@ options:
type: str
force:
description:
- If C(true), forcefully adds the deploy key by deleting any existing deploy key with the same public key or title.
- If V(true), forcefully adds the deploy key by deleting any existing deploy key with the same public key or title.
type: bool
default: false
username:
@ -78,15 +78,15 @@ options:
type: str
password:
description:
- The password to authenticate with. Alternatively, a personal access token can be used instead of I(username) and I(password) combination.
- The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(password) combination.
type: str
token:
description:
- The OAuth2 token or personal access token to authenticate with. Mutually exclusive with I(password).
- The OAuth2 token or personal access token to authenticate with. Mutually exclusive with O(password).
type: str
otp:
description:
- The 6 digit One Time Password for 2-Factor Authentication. Required together with I(username) and I(password).
- The 6 digit One Time Password for 2-Factor Authentication. Required together with O(username) and O(password).
type: int
notes:
- "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/."

8
plugins/modules/github_key.py
View file

@ -34,7 +34,7 @@ options:
type: str
pubkey:
description:
- SSH public key value. Required when I(state=present).
- SSH public key value. Required when O(state=present).
type: str
state:
description:
@ -44,9 +44,9 @@ options:
type: str
force:
description:
- The default is C(true), which will replace the existing remote key
if it's different than C(pubkey). If C(false), the key will only be
set if no key with the given I(name) exists.
- The default is V(true), which will replace the existing remote key
if it is different than O(pubkey). If V(false), the key will only be
set if no key with the given O(name) exists.
type: bool
default: true

28
plugins/modules/github_repo.py
View file

@ -15,7 +15,7 @@ short_description: Manage your repositories on Github
version_added: 2.2.0
description:
- Manages Github repositories using PyGithub library.
- Authentication can be done with I(access_token) or with I(username) and I(password).
- Authentication can be done with O(access_token) or with O(username) and O(password).
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -27,19 +27,19 @@ options:
username:
description:
- Username used for authentication.
- This is only needed when not using I(access_token).
- This is only needed when not using O(access_token).
type: str
required: false
password:
description:
- Password used for authentication.
- This is only needed when not using I(access_token).
- This is only needed when not using O(access_token).
type: str
required: false
access_token:
description:
- Token parameter for authentication.
- This is only needed when not using I(username) and I(password).
- This is only needed when not using O(username) and O(password).
type: str
required: false
name:
@ -50,17 +50,17 @@ options:
description:
description:
- Description for the repository.
- Defaults to empty if I(force_defaults=true), which is the default in this module.
- Defaults to empty if I(force_defaults=false) when creating a new repository.
- This is only used when I(state) is C(present).
- Defaults to empty if O(force_defaults=true), which is the default in this module.
- Defaults to empty if O(force_defaults=false) when creating a new repository.
- This is only used when O(state) is V(present).
type: str
required: false
private:
description:
- Whether the repository should be private or not.
- Defaults to C(false) if I(force_defaults=true), which is the default in this module.
- Defaults to C(false) if I(force_defaults=false) when creating a new repository.
- This is only used when I(state) is C(present).
- Defaults to V(false) if O(force_defaults=true), which is the default in this module.
- Defaults to V(false) if O(force_defaults=false) when creating a new repository.
- This is only used when O(state=present).
type: bool
required: false
state:
@ -73,7 +73,7 @@ options:
organization:
description:
- Organization for the repository.
- When I(state) is C(present), the repository will be created in the current user profile.
- When O(state=present), the repository will be created in the current user profile.
type: str
required: false
api_url:
@ -84,8 +84,8 @@ options:
version_added: "3.5.0"
force_defaults:
description:
- Overwrite current I(description) and I(private) attributes with defaults if set to C(true), which currently is the default.
- The default for this option will be deprecated in a future version of this collection, and eventually change to C(false).
- Overwrite current O(description) and O(private) attributes with defaults if set to V(true), which currently is the default.
- The default for this option will be deprecated in a future version of this collection, and eventually change to V(false).
type: bool
default: true
required: false
@ -125,7 +125,7 @@ EXAMPLES = '''
RETURN = '''
repo:
description: Repository information as JSON. See U(https://docs.github.com/en/rest/reference/repos#get-a-repository).
returned: success and I(state) is C(present)
returned: success and O(state=present)
type: dict
'''

2
plugins/modules/gitlab_branch.py
View file

@ -49,7 +49,7 @@ options:
ref_branch:
description:
- Reference branch to create from.
- This must be specified if I(state=present).
- This must be specified if O(state=present).
type: str
'''

20
plugins/modules/gitlab_group_members.py
View file

@ -40,22 +40,22 @@ options:
gitlab_user:
description:
- A username or a list of usernames to add to/remove from the GitLab group.
- Mutually exclusive with I(gitlab_users_access).
- Mutually exclusive with O(gitlab_users_access).
type: list
elements: str
access_level:
description:
- The access level for the user.
- Required if I(state=present), user state is set to present.
- Mutually exclusive with I(gitlab_users_access).
- Required if O(state=present), user state is set to present.
- Mutually exclusive with O(gitlab_users_access).
type: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
gitlab_users_access:
description:
- Provide a list of user to access level mappings.
- Every dictionary in this list specifies a user (by username) and the access level the user should have.
- Mutually exclusive with I(gitlab_user) and I(access_level).
- Use together with I(purge_users) to remove all users not specified here from the group.
- Mutually exclusive with O(gitlab_user) and O(access_level).
- Use together with O(purge_users) to remove all users not specified here from the group.
type: list
elements: dict
suboptions:
@ -66,7 +66,7 @@ options:
access_level:
description:
- The access level for the user.
- Required if I(state=present), user state is set to present.
- Required if O(state=present), user state is set to present.
type: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
required: true
@ -74,16 +74,16 @@ options:
state:
description:
- State of the member in the group.
- On C(present), it adds a user to a GitLab group.
- On C(absent), it removes a user from a GitLab group.
- On V(present), it adds a user to a GitLab group.
- On V(absent), it removes a user from a GitLab group.
choices: ['present', 'absent']
default: 'present'
type: str
purge_users:
description:
- Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list.
- Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list.
If omitted do not purge orphaned members.
- Is only used when I(state=present).
- Is only used when O(state=present).
type: list
elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']

16
plugins/modules/gitlab_group_variable.py
View file

@ -17,7 +17,7 @@ description:
- Creates a group variable if it does not exist.
- When a group variable does exist, its value will be updated when the values are different.
- Variables which are untouched in the playbook, but are not untouched in the GitLab group,
they stay untouched (I(purge) is C(false)) or will be deleted (I(purge) is C(true)).
they stay untouched (O(purge=false)) or will be deleted (O(purge=true)).
author:
- Florent Madiot (@scodeman)
requirements:
@ -48,20 +48,20 @@ options:
type: str
purge:
description:
- When set to C(true), delete all variables which are not untouched in the task.
- When set to V(true), delete all variables which are not untouched in the task.
default: false
type: bool
vars:
description:
- When the list element is a simple key-value pair, set masked and protected to false.
- When the list element is a dict with the keys I(value), I(masked) and I(protected), the user can
- When the list element is a dict with the keys C(value), C(masked) and C(protected), the user can
have full control about whether a value should be masked, protected or both.
- Support for group variables requires GitLab >= 9.5.
- Support for environment_scope requires GitLab Premium >= 13.11.
- Support for protected values requires GitLab >= 9.3.
- Support for masked values requires GitLab >= 11.10.
- A I(value) must be a string or a number.
- Field I(variable_type) must be a string with either C(env_var), which is the default, or C(file).
- A C(value) must be a string or a number.
- Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file).
- When a value is masked, it must be in Base64 and have a length of at least 8 characters.
See GitLab documentation on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)).
default: {}
@ -70,7 +70,7 @@ options:
version_added: 4.5.0
description:
- A list of dictionaries that represents CI/CD variables.
- This modules works internal with this sructure, even if the older I(vars) parameter is used.
- This modules works internal with this sructure, even if the older O(vars) parameter is used.
default: []
type: list
elements: dict
@ -83,7 +83,7 @@ options:
value:
description:
- The variable value.
- Required when I(state=present).
- Required when O(state=present).
type: str
masked:
description:
@ -97,7 +97,7 @@ options:
default: false
variable_type:
description:
- Wether a variable is an environment variable (C(env_var)) or a file (C(file)).
- Wether a variable is an environment variable (V(env_var)) or a file (V(file)).
type: str
choices: [ "env_var", "file" ]
default: env_var

8
plugins/modules/gitlab_instance_variable.py
View file

@ -19,7 +19,7 @@ description:
- When a instance variable does exist, its value will be updated if the values are different.
- Support for instance variables requires GitLab >= 13.0.
- Variables which are not mentioned in the modules options, but are present on the GitLab instance,
will either stay (I(purge=false)) or will be deleted (I(purge=true)).
will either stay (O(purge=false)) or will be deleted (O(purge=true)).
author:
- Benedikt Braunger (@benibr)
requirements:
@ -45,7 +45,7 @@ options:
choices: ["present", "absent"]
purge:
description:
- When set to C(true), delete all variables which are not mentioned in the task.
- When set to V(true), delete all variables which are not mentioned in the task.
default: false
type: bool
variables:
@ -63,7 +63,7 @@ options:
value:
description:
- The variable value.
- Required when I(state=present).
- Required when O(state=present).
type: str
masked:
description:
@ -77,7 +77,7 @@ options:
default: false
variable_type:
description:
- Wether a variable is an environment variable (C(env_var)) or a file (C(file)).
- Wether a variable is an environment variable (V(env_var)) or a file (V(file)).
type: str
choices: [ "env_var", "file" ]
default: env_var

66
plugins/modules/gitlab_project.py
View file

@ -15,7 +15,7 @@ module: gitlab_project
short_description: Creates/updates/deletes GitLab Projects
description:
- When the project does not exist in GitLab, it will be created.
- When the project does exists and I(state=absent), the project will be deleted.
- When the project does exists and O(state=absent), the project will be deleted.
- When changes are made to the project, the project will be updated.
author:
- Werner Dijkerman (@dj-wasabi)
@ -84,9 +84,9 @@ options:
default: true
visibility:
description:
- C(private) Project access must be granted explicitly for each user.
- C(internal) The project can be cloned by any logged in user.
- C(public) The project can be cloned without any authentication.
- V(private) Project access must be granted explicitly for each user.
- V(internal) The project can be cloned by any logged in user.
- V(public) The project can be cloned without any authentication.
default: private
type: str
choices: ["private", "internal", "public"]
@ -108,7 +108,7 @@ options:
merge_method:
description:
- What requirements are placed upon merges.
- Possible values are C(merge), C(rebase_merge) merge commit with semi-linear history, C(ff) fast-forward merges only.
- Possible values are V(merge), V(rebase_merge) merge commit with semi-linear history, V(ff) fast-forward merges only.
type: str
choices: ["ff", "merge", "rebase_merge"]
default: merge
@ -176,78 +176,78 @@ options:
default_branch:
description:
- Default branch name for a new project.
- This option is only used on creation, not for updates. This is also only used if I(initialize_with_readme=true).
- This option is only used on creation, not for updates. This is also only used if O(initialize_with_readme=true).
type: str
version_added: "4.2.0"
builds_access_level:
description:
- C(private) means that repository CI/CD is allowed only to project members.
- C(disabled) means that repository CI/CD is disabled.
- C(enabled) means that repository CI/CD is enabled.
- V(private) means that repository CI/CD is allowed only to project members.
- V(disabled) means that repository CI/CD is disabled.
- V(enabled) means that repository CI/CD is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.2.0"
forking_access_level:
description:
- C(private) means that repository forks is allowed only to project members.
- C(disabled) means that repository forks are disabled.
- C(enabled) means that repository forks are enabled.
- V(private) means that repository forks is allowed only to project members.
- V(disabled) means that repository forks are disabled.
- V(enabled) means that repository forks are enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.2.0"
container_registry_access_level:
description:
- C(private) means that container registry is allowed only to project members.
- C(disabled) means that container registry is disabled.
- C(enabled) means that container registry is enabled.
- V(private) means that container registry is allowed only to project members.
- V(disabled) means that container registry is disabled.
- V(enabled) means that container registry is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.2.0"
releases_access_level:
description:
- C(private) means that accessing release is allowed only to project members.
- C(disabled) means that accessing release is disabled.
- C(enabled) means that accessing release is enabled.
- V(private) means that accessing release is allowed only to project members.
- V(disabled) means that accessing release is disabled.
- V(enabled) means that accessing release is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.4.0"
environments_access_level:
description:
- C(private) means that deployment to environment is allowed only to project members.
- C(disabled) means that deployment to environment is disabled.
- C(enabled) means that deployment to environment is enabled.
- V(private) means that deployment to environment is allowed only to project members.
- V(disabled) means that deployment to environment is disabled.
- V(enabled) means that deployment to environment is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.4.0"
feature_flags_access_level:
description:
- C(private) means that feature rollout is allowed only to project members.
- C(disabled) means that feature rollout is disabled.
- C(enabled) means that feature rollout is enabled.
- V(private) means that feature rollout is allowed only to project members.
- V(disabled) means that feature rollout is disabled.
- V(enabled) means that feature rollout is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.4.0"
infrastructure_access_level:
description:
- C(private) means that configuring infrastructure is allowed only to project members.
- C(disabled) means that configuring infrastructure is disabled.
- C(enabled) means that configuring infrastructure is enabled.
- V(private) means that configuring infrastructure is allowed only to project members.
- V(disabled) means that configuring infrastructure is disabled.
- V(enabled) means that configuring infrastructure is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.4.0"
monitor_access_level:
description:
- C(private) means that monitoring health is allowed only to project members.
- C(disabled) means that monitoring health is disabled.
- C(enabled) means that monitoring health is enabled.
- V(private) means that monitoring health is allowed only to project members.
- V(disabled) means that monitoring health is disabled.
- V(enabled) means that monitoring health is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.4.0"
security_and_compliance_access_level:
description:
- C(private) means that accessing security and complicance tab is allowed only to project members.
- C(disabled) means that accessing security and complicance tab is disabled.
- C(enabled) means that accessing security and complicance tab is enabled.
- V(private) means that accessing security and complicance tab is allowed only to project members.
- V(disabled) means that accessing security and complicance tab is disabled.
- V(enabled) means that accessing security and complicance tab is enabled.
type: str
choices: ["private", "disabled", "enabled"]
version_added: "6.4.0"

6
plugins/modules/gitlab_project_badge.py
View file

@ -39,8 +39,8 @@ options:
state:
description:
- State of the badge in the project.
- On C(present), it adds a badge to a GitLab project.
- On C(absent), it removes a badge from a GitLab project.
- On V(present), it adds a badge to a GitLab project.
- On V(absent), it removes a badge from a GitLab project.
choices: ['present', 'absent']
default: 'present'
type: str
@ -82,7 +82,7 @@ EXAMPLES = r'''
RETURN = '''
badge:
description: The badge information.
returned: when I(state=present)
returned: when O(state=present)
type: dict
sample:
id: 1

18
plugins/modules/gitlab_project_members.py
View file

@ -42,21 +42,21 @@ options:
gitlab_user:
description:
- A username or a list of usernames to add to/remove from the GitLab project.
- Mutually exclusive with I(gitlab_users_access).
- Mutually exclusive with O(gitlab_users_access).
type: list
elements: str
access_level:
description:
- The access level for the user.
- Required if I(state=present), user state is set to present.
- Required if O(state=present), user state is set to present.
type: str
choices: ['guest', 'reporter', 'developer', 'maintainer']
gitlab_users_access:
description:
- Provide a list of user to access level mappings.
- Every dictionary in this list specifies a user (by username) and the access level the user should have.
- Mutually exclusive with I(gitlab_user) and I(access_level).
- Use together with I(purge_users) to remove all users not specified here from the project.
- Mutually exclusive with O(gitlab_user) and O(access_level).
- Use together with O(purge_users) to remove all users not specified here from the project.
type: list
elements: dict
suboptions:
@ -67,7 +67,7 @@ options:
access_level:
description:
- The access level for the user.
- Required if I(state=present), user state is set to present.
- Required if O(state=present), user state is set to present.
type: str
choices: ['guest', 'reporter', 'developer', 'maintainer']
required: true
@ -75,16 +75,16 @@ options:
state:
description:
- State of the member in the project.
- On C(present), it adds a user to a GitLab project.
- On C(absent), it removes a user from a GitLab project.
- On V(present), it adds a user to a GitLab project.
- On V(absent), it removes a user from a GitLab project.
choices: ['present', 'absent']
default: 'present'
type: str
purge_users:
description:
- Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list.
- Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list.
If omitted do not purge orphaned members.
- Is only used when I(state=present).
- Is only used when O(state=present).
type: list
elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer']

20
plugins/modules/gitlab_project_variable.py
View file

@ -14,7 +14,7 @@ description:
- When a project variable does not exist, it will be created.
- When a project variable does exist, its value will be updated when the values are different.
- Variables which are untouched in the playbook, but are not untouched in the GitLab project,
they stay untouched (I(purge) is C(false)) or will be deleted (I(purge) is C(true)).
they stay untouched (O(purge=false)) or will be deleted (O(purge=true)).
author:
- "Markus Bergholz (@markuman)"
requirements:
@ -52,15 +52,15 @@ options:
vars:
description:
- When the list element is a simple key-value pair, masked and protected will be set to false.
- When the list element is a dict with the keys I(value), I(masked) and I(protected), the user can
- When the list element is a dict with the keys C(value), C(masked) and C(protected), the user can
have full control about whether a value should be masked, protected or both.
- Support for protected values requires GitLab >= 9.3.
- Support for masked values requires GitLab >= 11.10.
- Support for environment_scope requires GitLab Premium >= 13.11.
- Support for variable_type requires GitLab >= 11.11.
- A I(value) must be a string or a number.
- Field I(variable_type) must be a string with either C(env_var), which is the default, or C(file).
- Field I(environment_scope) must be a string defined by scope environment.
- A C(value) must be a string or a number.
- Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file).
- Field C(environment_scope) must be a string defined by scope environment.
- When a value is masked, it must be in Base64 and have a length of at least 8 characters.
See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).
default: {}
@ -69,7 +69,7 @@ options:
version_added: 4.4.0
description:
- A list of dictionaries that represents CI/CD variables.
- This module works internal with this structure, even if the older I(vars) parameter is used.
- This module works internal with this structure, even if the older O(vars) parameter is used.
default: []
type: list
elements: dict
@ -82,7 +82,7 @@ options:
value:
description:
- The variable value.
- Required when I(state=present).
- Required when O(state=present).
type: str
masked:
description:
@ -98,15 +98,15 @@ options:
default: false
variable_type:
description:
- Wether a variable is an environment variable (C(env_var)) or a file (C(file)).
- Support for I(variable_type) requires GitLab >= 11.11.
- Wether a variable is an environment variable (V(env_var)) or a file (V(file)).
- Support for O(variables[].variable_type) requires GitLab >= 11.11.
type: str
choices: ["env_var", "file"]
default: env_var
environment_scope:
description:
- The scope for the variable.
- Support for I(environment_scope) requires GitLab Premium >= 13.11.
- Support for O(variables[].environment_scope) requires GitLab Premium >= 13.11.
type: str
default: '*'
'''

30
plugins/modules/gitlab_runner.py
View file

@ -24,7 +24,7 @@ description:
To create shared runners, you need to ask your administrator to give you this token.
It can be found at U(https://$GITLAB_URL/admin/runners/).
notes:
- To create a new runner at least the C(api_token), C(description) and C(api_url) options are required.
- To create a new runner at least the O(api_token), O(description) and O(api_url) options are required.
- Runners need to have unique descriptions.
author:
- Samy Coenen (@SamyCoenen)
@ -47,14 +47,14 @@ options:
group:
description:
- ID or full path of the group in the form group/subgroup.
- Mutually exclusive with I(owned) and I(project).
- Mutually exclusive with O(owned) and O(project).
type: str
version_added: '6.5.0'
project:
description:
- ID or full path of the project in the form of group/name.
- Mutually exclusive with I(owned) since community.general 4.5.0.
- Mutually exclusive with I(group).
- Mutually exclusive with O(owned) since community.general 4.5.0.
- Mutually exclusive with O(group).
type: str
version_added: '3.7.0'
description:
@ -74,13 +74,13 @@ options:
registration_token:
description:
- The registration token is used to register new runners.
- Required if I(state) is C(present).
- Required if O(state=present).
type: str
owned:
description:
- Searches only runners available to the user when searching for existing, when false admin token required.
- Mutually exclusive with I(project) since community.general 4.5.0.
- Mutually exclusive with I(group).
- Mutually exclusive with O(project) since community.general 4.5.0.
- Mutually exclusive with O(group).
default: false
type: bool
version_added: 2.0.0
@ -99,12 +99,12 @@ options:
access_level:
description:
- Determines if a runner can pick up jobs only from protected branches.
- If I(access_level_on_creation) is not explicitly set to C(true), this option is ignored on registration and
- If O(access_level_on_creation) is not explicitly set to V(true), this option is ignored on registration and
is only applied on updates.
- If set to C(not_protected), runner can pick up jobs from both protected and unprotected branches.
- If set to C(ref_protected), runner can pick up jobs only from protected branches.
- The current default is C(ref_protected). This will change to no default in community.general 8.0.0.
From that version on, if this option is not specified explicitly, GitLab will use C(not_protected)
- If set to V(not_protected), runner can pick up jobs from both protected and unprotected branches.
- If set to V(ref_protected), runner can pick up jobs only from protected branches.
- The current default is V(ref_protected). This will change to no default in community.general 8.0.0.
From that version on, if this option is not specified explicitly, GitLab will use V(not_protected)
on creation, and the value set will not be changed on any updates.
required: false
choices: ["not_protected", "ref_protected"]
@ -112,9 +112,9 @@ options:
access_level_on_creation:
description:
- Whether the runner should be registered with an access level or not.
- If set to C(true), the value of I(access_level) is used for runner registration.
- If set to C(false), GitLab registers the runner with the default access level.
- The default of this option changed to C(true) in community.general 7.0.0. Before, it was C(false).
- If set to V(true), the value of O(access_level) is used for runner registration.
- If set to V(false), GitLab registers the runner with the default access level.
- The default of this option changed to V(true) in community.general 7.0.0. Before, it was V(false).
required: false
default: true
type: bool

10
plugins/modules/gitlab_user.py
View file

@ -45,7 +45,7 @@ options:
name:
description:
- Name of the user you want to create.
- Required only if C(state) is set to C(present).
- Required only if O(state=present).
type: str
username:
description:
@ -66,7 +66,7 @@ options:
email:
description:
- The email that belongs to the user.
- Required only if C(state) is set to C(present).
- Required only if O(state=present).
type: str
sshkey_name:
description:
@ -123,7 +123,7 @@ options:
identities:
description:
- List of identities to be added/updated for this user.
- To remove all other identities from this user, set I(overwrite_identities=true).
- To remove all other identities from this user, set O(overwrite_identities=true).
type: list
elements: dict
suboptions:
@ -139,8 +139,8 @@ options:
overwrite_identities:
description:
- Overwrite identities with identities added in this module.
- This means that all identities that the user has and that are not listed in I(identities) are removed from the user.
- This is only done if a list is provided for I(identities). To remove all identities, provide an empty list.
- This means that all identities that the user has and that are not listed in O(identities) are removed from the user.
- This is only done if a list is provided for O(identities). To remove all identities, provide an empty list.
type: bool
default: false
version_added: 3.3.0

2
plugins/modules/grove.py
View file

@ -39,7 +39,7 @@ options:
type: str
description:
- Message content.
- The alias I(message) is deprecated and will be removed in community.general 4.0.0.
- The alias O(ignore:message) has been removed in community.general 4.0.0.
required: true
url:
type: str