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: description:
- Manages monitors within Datadog. - Manages monitors within Datadog.
- Options as described on https://docs.datadoghq.com/api/. - 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) author: Sebastian Kornehl (@skornehl)
requirements: [datadog] requirements: [datadog]
extends_documentation_fragment: extends_documentation_fragment:
@ -34,8 +33,8 @@ options:
type: str type: str
api_host: api_host:
description: description:
- The URL to the Datadog API. Default value is C(https://api.datadoghq.com). - The URL to the Datadog API. Default value is V(https://api.datadoghq.com).
- This value can also be set with the C(DATADOG_HOST) environment variable. - This value can also be set with the E(DATADOG_HOST) environment variable.
required: false required: false
type: str type: str
version_added: '0.2.0' version_added: '0.2.0'
@ -59,8 +58,9 @@ options:
type: type:
description: description:
- The type of the monitor. - 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 types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0.
- The type C(composite) was added in community.general 3.4.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: choices:
- metric alert - metric alert
- service check - service check
@ -117,7 +117,7 @@ options:
escalation_message: escalation_message:
description: description:
- A message to include with a re-notification. Supports the '@username' notification we allow elsewhere. - 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 type: str
notify_audit: notify_audit:
description: description:
@ -130,7 +130,7 @@ options:
- A dictionary of thresholds by status. - A dictionary of thresholds by status.
- Only available for service checks and metric alerts. - 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. - 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: locked:
description: description:
- Whether changes to this monitor should be restricted to the creator or admins. - 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. - The Deploy Helper manages some of the steps common in deploying software.
It creates a folder structure, manages a symlink for the current release It creates a folder structure, manages a symlink for the current release
and cleans up old releases. and cleans up old releases.
- "Running it with the I(state=query) or I(state=present) will return the C(deploy_helper) fact. # TODO: convert below to RETURN documentation!
C(project_path), whatever you set in the I(path) parameter, - "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(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(releases_path), the path to the folder to keep releases in,
C(shared_path), the path to the folder to keep shared resources in, C(shared_path), the path to the folder to keep shared resources in,
@ -50,33 +51,33 @@ options:
type: str type: str
description: description:
- The state of the project. - The state of the project.
C(query) will only gather facts, - V(query) will only gather facts.
C(present) will create the project I(root) folder, and in it the I(releases) and I(shared) folders, - V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders.
C(finalize) will remove the unfinished_filename file, create a symlink to the newly - V(finalize) will remove the unfinished_filename file, create a symlink to the newly
deployed release and optionally clean old releases, deployed release and optionally clean old releases.
C(clean) will remove failed & old releases, - V(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(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)).
choices: [ present, finalize, absent, clean, query ] choices: [ present, finalize, absent, clean, query ]
default: present default: present
release: release:
type: str type: str
description: description:
- The release version that is being deployed. Defaults to a timestamp format %Y%m%d%H%M%S (i.e. '20141119223359'). - 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 I(state=present), but needs to be set explicitly for I(state=finalize). This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize).
You can use the generated fact I(release={{ deploy_helper.new_release }}). You can use the generated fact C(release={{ deploy_helper.new_release }}).
releases_path: releases_path:
type: str type: str
description: 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. Returned in the C(deploy_helper.releases_path) fact.
default: releases default: releases
shared_path: shared_path:
type: path type: path
description: 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. If this is set to an empty string, no shared folder will be created.
Returned in the C(deploy_helper.shared_path) fact. Returned in the C(deploy_helper.shared_path) fact.
default: shared default: shared
@ -84,38 +85,38 @@ options:
current_path: current_path:
type: path type: path
description: 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. Returned in the C(deploy_helper.current_path) fact.
default: current default: current
unfinished_filename: unfinished_filename:
type: str type: str
description: description:
- The name of the file that indicates a deploy has not finished. All folders in the I(releases_path) that - 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 I(state=finalize) with I(clean=True), or I(state=clean). This file is 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 I(new_release_path) during I(state=finalize). automatically deleted from the C(new_release_path) during O(state=finalize).
default: DEPLOY_UNFINISHED default: DEPLOY_UNFINISHED
clean: clean:
description: 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 type: bool
default: true default: true
keep_releases: keep_releases:
type: int type: int
description: 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. will be deleted first, so only correct releases will count. The current version will not count.
default: 5 default: 5
notes: 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. 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. new naming strategy without problems.
- Because of the default behaviour of generating the I(new_release) fact, this module will not be idempotent - 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 I(release). Due to the nature of deploying software, this should not 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. be much of a problem.
extends_documentation_fragment: extends_documentation_fragment:
- ansible.builtin.files - ansible.builtin.files

2
plugins/modules/dimensiondata_network.py
View file

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

8
plugins/modules/dimensiondata_vlan.py
View file

@ -51,20 +51,20 @@ options:
private_ipv4_prefix_size: private_ipv4_prefix_size:
description: description:
- The size of the IPv4 address space, e.g 24. - 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 type: int
default: 0 default: 0
state: state:
description: description:
- The desired state for the target VLAN. - 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] choices: [present, absent, readonly]
default: present default: present
type: str type: str
allow_expand: allow_expand:
description: description:
- Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses. - 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). - This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible).
type: bool type: bool
default: false default: false
@ -105,7 +105,7 @@ EXAMPLES = '''
RETURN = ''' RETURN = '''
vlan: vlan:
description: Dictionary describing the VLAN. description: Dictionary describing the VLAN.
returned: On success when I(state) is 'present' returned: On success when O(state=present)
type: complex type: complex
contains: contains:
id: id:

6
plugins/modules/discord.py
View file

@ -43,7 +43,7 @@ options:
content: content:
description: description:
- Content of the message to the Discord channel. - 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 type: str
username: username:
description: description:
@ -55,7 +55,7 @@ options:
type: str type: str
tts: tts:
description: 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 type: bool
default: false default: false
embeds: embeds:
@ -63,7 +63,7 @@ options:
- Send messages as Embeds to the Discord channel. - Send messages as Embeds to the Discord channel.
- Embeds can have a colored border, embedded images, text fields and more. - 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)" - "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 type: list
elements: dict elements: dict
''' '''

70
plugins/modules/django_manage.py
View file

@ -16,7 +16,7 @@ module: django_manage
short_description: Manages a Django application short_description: Manages a Django application
description: description:
- Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the - 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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -29,20 +29,20 @@ options:
description: 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. - 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 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 C(clearsessions) instead. removed in community.general 9.0.0. Use V(clearsessions) instead.
- C(collectstatic) - Collects the static files into C(STATIC_ROOT). - V(collectstatic) - Collects the static files into C(STATIC_ROOT).
- C(createcachetable) - Creates the cache tables for use with the database cache backend. - V(createcachetable) - Creates the cache tables for use with the database cache backend.
- C(flush) - Removes all data from the database. - V(flush) - Removes all data from the database.
- C(loaddata) - Searches for and loads the contents of the named I(fixtures) into the database. - V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database.
- C(migrate) - Synchronizes the database state with models and migrations. - 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). 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 C(migrate) instead. This parameter will be removed in community.general 9.0.0. Use V(migrate) instead.
- C(test) - Runs tests for all installed apps. - V(test) - Runs tests for all installed apps.
- > - >
C(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be V(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. 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 - 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. prompt for user input should be run with the C(--noinput) flag.
type: str type: str
@ -55,14 +55,14 @@ options:
aliases: [app_path, chdir] aliases: [app_path, chdir]
settings: settings:
description: 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 type: path
required: false required: false
pythonpath: pythonpath:
description: description:
- A directory to add to the Python path. Typically used to include the settings module if it is located - A directory to add to the Python path. Typically used to include the settings module if it is located
external to the application directory. 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 type: path
required: false required: false
aliases: [python_path] aliases: [python_path]
@ -73,54 +73,54 @@ options:
aliases: [virtual_env] aliases: [virtual_env]
apps: apps:
description: 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 type: str
required: false required: false
cache_table: cache_table:
description: 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 type: str
required: false required: false
clear: clear:
description: description:
- Clear the existing files before trying to copy or link the original file. - 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 required: false
default: false default: false
type: bool type: bool
database: database:
description: description:
- The database to target. Used by the C(createcachetable), C(flush), C(loaddata), C(syncdb), - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb),
and C(migrate) commands. and V(migrate) commands.
type: str type: str
required: false required: false
failfast: failfast:
description: 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 required: false
default: false default: false
type: bool type: bool
aliases: [fail_fast] aliases: [fail_fast]
fixtures: fixtures:
description: 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 type: str
required: false required: false
skip: skip:
description: 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 required: false
type: bool type: bool
merge: merge:
description: description:
- Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this - 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 required: false
type: bool type: bool
link: link:
description: description:
- Will create links to the files instead of copying them, you can only use this parameter with - 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 required: false
type: bool type: bool
testrunner: testrunner:
@ -133,9 +133,9 @@ options:
ack_venv_creation_deprecation: ack_venv_creation_deprecation:
description: 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 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 - 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. will start failing in such cases from community.general 9.0.0 on.
type: bool type: bool
@ -146,19 +146,19 @@ notes:
B(ATTENTION - DEPRECATION): Support for Django releases older than 4.1 will be removed in 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). 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. 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. 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. 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). 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. 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. as an app in your settings.
- To be able to use the C(collectstatic) command, you must have enabled staticfiles in your settings. - 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 (rwxr-xr-x), and must have a valid shebang, - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang,
i.e. C(#!/usr/bin/env python), for invoking the appropriate Python interpreter. for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter.
seealso: seealso:
- name: django-admin and manage.py Reference - name: django-admin and manage.py Reference
description: Reference for C(django-admin) or C(manage.py) commands. 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: description:
- Package name spec to add or exclude to or delete from the C(locklist) - Package name spec to add or exclude to or delete from the C(locklist)
using the format expected by the C(dnf repoquery) command. 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 type: list
required: false required: false
elements: str elements: str
@ -52,19 +52,19 @@ options:
default: false default: false
state: state:
description: description:
- Whether to add (C(present) or C(excluded)) to or remove (C(absent) or - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or
C(clean)) from the C(locklist). V(clean)) from the C(locklist).
- C(present) will add a package name spec to the C(locklist). If there is a - 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. installed package that matches, then only that version will be added.
Otherwise, all available package versions 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 C(locklist). It means that packages represented by the package name
spec will be excluded from transaction operations. All available spec will be excluded from transaction operations. All available
package versions will be added. 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. package name spec.
- C(clean) will delete all entries in the C(locklist). This option is - V(clean) will delete all entries in the C(locklist). This option is
mutually exclusive with C(name). mutually exclusive with O(name).
choices: [ 'absent', 'clean', 'excluded', 'present' ] choices: [ 'absent', 'clean', 'excluded', 'present' ]
type: str type: str
default: present default: present

4
plugins/modules/dnsimple.py
View file

@ -32,7 +32,7 @@ options:
type: str type: str
account_api_token: account_api_token:
description: description:
- Account API token. See I(account_email) for more information. - Account API token. See O(account_email) for more information.
type: str type: str
domain: domain:
description: description:
@ -77,7 +77,7 @@ options:
solo: solo:
description: description:
- Whether the record should be the only one for that record type and record name. - 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' type: 'bool'
default: false default: false
sandbox: 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. description: Returns a list of dictionaries of all domains associated with the supplied account ID.
type: list type: list
elements: dict elements: dict
returned: success when I(name) is not specified returned: success when O(name) is not specified
sample: sample:
- account_id: 1234 - account_id: 1234
created_at: '2021-10-16T21:25:42Z' 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. description: Returns a list of dictionaries with all records for the domain supplied.
type: list type: list
elements: dict 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: sample:
- content: ns1.dnsimple.com admin.dnsimple.com - content: ns1.dnsimple.com admin.dnsimple.com
created_at: '2021-10-16T19:07:34Z' created_at: '2021-10-16T19:07:34Z'
@ -174,7 +174,7 @@ dnsimple_records_info:
type: str type: str
dnsimple_record_info: dnsimple_record_info:
description: Returns a list of dictionaries that match the record supplied. 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 type: list
elements: dict elements: dict
sample: 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 - 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 (or the local administrator) is allowed to install a file at a given
location. Other packages shipping their own version of this file will 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 allows one to keep changes in a file provided by a debian package by
preventing its overwrite at package upgrade. preventing its overwrite at package upgrade.
- This module manages diversions of debian packages files using the - This module manages diversions of debian packages files using the
C(dpkg-divert) commandline tool. It can either create or remove a C(dpkg-divert) commandline tool. It can either create or remove a
diversion for a given file, but also update an existing diversion 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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -39,14 +39,14 @@ options:
description: description:
- The original and absolute path of the file to be diverted or - 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 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 required: true
type: path type: path
state: state:
description: description:
- When I(state=absent), remove the diversion of the specified - When O(state=absent), remove the diversion of the specified
I(path); when I(state=present), create the diversion if it does O(path); when O(state=present), create the diversion if it does
not exist, or update its package I(holder) or I(divert) location, not exist, or update its package O(holder) or O(divert) location,
if it already exists. if it already exists.
type: str type: str
default: present default: present
@ -59,31 +59,31 @@ options:
- The actual package does not have to be installed or even to exist - 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 for its name to be valid. If not specified, the diversion is hold
by 'LOCAL', that is reserved by/for dpkg for local diversions. 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 type: str
divert: divert:
description: description:
- The location where the versions of file will be diverted. - The location where the versions of file will be diverted.
- Default is to add suffix C(.distrib) to the file path. - 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 type: path
rename: rename:
description: description:
- Actually move the file aside (when I(state=present)) or back (when - Actually move the file aside (when O(state=present)) or back (when
I(state=absent)), but only when changing the state of the diversion. O(state=absent)), but only when changing the state of the diversion.
This parameter has no effect when attempting to add a diversion that This parameter has no effect when attempting to add a diversion that
already exists or when removing an unexisting one. 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 exists (this lock being a dpkg-divert feature, and bypassing it being
a module feature). a module feature).
type: bool type: bool
default: false default: false
force: force:
description: 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 the target of the renaming exists, i.e. the existing contents of the
file at this location will be lost. 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 type: bool
default: false default: false
requirements: requirements:

18
plugins/modules/easy_install.py
View file

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

8
plugins/modules/etcd3.py
View file

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

2
plugins/modules/facter.py
View file

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

38
plugins/modules/filesize.py
View file

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

28
plugins/modules/filesystem.py
View file

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

14
plugins/modules/flatpak.py
View file

@ -39,8 +39,8 @@ options:
method: method:
description: description:
- The installation method to use. - The installation method to use.
- Defines if the I(flatpak) is supposed to be installed globally for the whole C(system) - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system)
or only for the current C(user). or only for the current V(user).
type: str type: str
choices: [ system, user ] choices: [ system, user ]
default: system default: system
@ -48,14 +48,14 @@ options:
description: description:
- The name of the flatpak to manage. To operate on several packages this - The name of the flatpak to manage. To operate on several packages this
can accept a list of packages. 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. C(flatpakref) file or the unique reverse DNS name that identifies a flatpak.
- Both C(https://) and C(http://) URLs are supported. - 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). 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. 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 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 guarantee that the names of the flatpakref file and the reverse DNS name of the installed
flatpak do match. flatpak do match.
@ -74,7 +74,7 @@ options:
remote: remote:
description: description:
- The flatpak remote (repository) to install the flatpak from. - 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. you can use this.
- See the M(community.general.flatpak_remote) module for managing flatpak remotes. - See the M(community.general.flatpak_remote) module for managing flatpak remotes.
type: str type: str

22
plugins/modules/flatpak_remote.py
View file

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

4
plugins/modules/gandi_livedns.py
View file

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

16
plugins/modules/gconftool2.py
View file

@ -36,18 +36,18 @@ options:
description: description:
- Preference keys typically have simple values such as strings, - Preference keys typically have simple values such as strings,
integers, or lists of strings and integers. 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: value_type:
type: str type: str
description: description:
- The type of value being set. - 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 ] choices: [ bool, float, int, string ]
state: state:
type: str type: str
description: description:
- The action to take upon the key/value. - 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 required: true
choices: [ absent, get, present ] choices: [ absent, get, present ]
config_source: config_source:
@ -57,8 +57,8 @@ options:
See man gconftool-2(1). See man gconftool-2(1).
direct: direct:
description: description:
- Access the config database directly, bypassing server. If I(direct) is - Access the config database directly, bypassing server. If O(direct) is
specified then the I(config_source) must be specified as well. specified then the O(config_source) must be specified as well.
See man gconftool-2(1). See man gconftool-2(1).
type: bool type: bool
default: false default: false
@ -85,15 +85,15 @@ RETURN = '''
sample: string sample: string
value: value:
description: description:
- The value of the preference key after executing the module or C(null) if key is removed. - 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 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 returned: success
type: str type: str
sample: "Serif 12" sample: "Serif 12"
previous_value: previous_value:
description: description:
- The value of the preference key before executing the module. - 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 returned: success
type: str type: str
sample: "Serif 12" sample: "Serif 12"

20
plugins/modules/git_config.py
View file

@ -20,7 +20,7 @@ author:
requirements: ['git'] requirements: ['git']
short_description: Read and write git configuration short_description: Read and write git configuration
description: 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 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 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 /etc/.git/config). Solutions involving M(ansible.builtin.command) are cumbersome or
@ -35,7 +35,7 @@ attributes:
options: options:
list_all: list_all:
description: description:
- List all settings (optionally limited to a given I(scope)). - List all settings (optionally limited to a given O(scope)).
type: bool type: bool
default: false default: false
name: name:
@ -50,23 +50,23 @@ options:
type: path type: path
file: file:
description: 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 type: path
version_added: 2.0.0 version_added: 2.0.0
scope: scope:
description: description:
- Specify which scope to read/set values from. - Specify which scope to read/set values from.
- This is required when setting config values. - 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 V(local), you must also specify the O(repo) parameter.
- If this is set to C(file), you must also specify the C(file) parameter. - If this is set to V(file), you must also specify the O(file) parameter.
- It defaults to system only when not using I(list_all)=C(true). - It defaults to system only when not using O(list_all=true).
choices: [ "file", "local", "global", "system" ] choices: [ "file", "local", "global", "system" ]
type: str type: str
state: state:
description: description:
- "Indicates the setting should be set/unset. - "Indicates the setting should be set/unset.
This parameter has higher precedence than I(value) parameter: This parameter has higher precedence than O(value) parameter:
when I(state)=absent and I(value) is defined, I(value) is discarded." when O(state=absent) and O(value) is defined, O(value) is discarded."
choices: [ 'present', 'absent' ] choices: [ 'present', 'absent' ]
default: 'present' default: 'present'
type: str type: str
@ -152,13 +152,13 @@ EXAMPLES = '''
RETURN = ''' RETURN = '''
--- ---
config_value: 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 returned: success
type: str type: str
sample: "vim" sample: "vim"
config_values: 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 returned: success
type: dict type: dict
sample: sample:

10
plugins/modules/github_deploy_key.py
View file

@ -58,7 +58,7 @@ options:
type: str type: str
read_only: read_only:
description: 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 type: bool
default: true default: true
state: state:
@ -69,7 +69,7 @@ options:
type: str type: str
force: force:
description: 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 type: bool
default: false default: false
username: username:
@ -78,15 +78,15 @@ options:
type: str type: str
password: password:
description: 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 type: str
token: token:
description: 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 type: str
otp: otp:
description: 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 type: int
notes: notes:
- "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/." - "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 type: str
pubkey: pubkey:
description: description:
- SSH public key value. Required when I(state=present). - SSH public key value. Required when O(state=present).
type: str type: str
state: state:
description: description:
@ -44,9 +44,9 @@ options:
type: str type: str
force: force:
description: description:
- The default is C(true), which will replace the existing remote key - The default is V(true), which will replace the existing remote key
if it's different than C(pubkey). If C(false), the key will only be if it is different than O(pubkey). If V(false), the key will only be
set if no key with the given I(name) exists. set if no key with the given O(name) exists.
type: bool type: bool
default: true 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 version_added: 2.2.0
description: description:
- Manages Github repositories using PyGithub library. - 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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -27,19 +27,19 @@ options:
username: username:
description: description:
- Username used for authentication. - 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 type: str
required: false required: false
password: password:
description: description:
- Password used for authentication. - 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 type: str
required: false required: false
access_token: access_token:
description: description:
- Token parameter for authentication. - 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 type: str
required: false required: false
name: name:
@ -50,17 +50,17 @@ options:
description: description:
description: description:
- Description for the repository. - Description for the repository.
- Defaults to empty if I(force_defaults=true), which is the default in this module. - Defaults to empty if O(force_defaults=true), which is the default in this module.
- Defaults to empty if I(force_defaults=false) when creating a new repository. - Defaults to empty if O(force_defaults=false) when creating a new repository.
- This is only used when I(state) is C(present). - This is only used when O(state) is V(present).
type: str type: str
required: false required: false
private: private:
description: description:
- Whether the repository should be private or not. - 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 V(false) if O(force_defaults=true), which is the default in this module.
- Defaults to C(false) if I(force_defaults=false) when creating a new repository. - Defaults to V(false) if O(force_defaults=false) when creating a new repository.
- This is only used when I(state) is C(present). - This is only used when O(state=present).
type: bool type: bool
required: false required: false
state: state:
@ -73,7 +73,7 @@ options:
organization: organization:
description: description:
- Organization for the repository. - 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 type: str
required: false required: false
api_url: api_url:
@ -84,8 +84,8 @@ options:
version_added: "3.5.0" version_added: "3.5.0"
force_defaults: force_defaults:
description: description:
- Overwrite current I(description) and I(private) attributes with defaults if set to C(true), which currently is the default. - 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 C(false). - The default for this option will be deprecated in a future version of this collection, and eventually change to V(false).
type: bool type: bool
default: true default: true
required: false required: false
@ -125,7 +125,7 @@ EXAMPLES = '''
RETURN = ''' RETURN = '''
repo: repo:
description: Repository information as JSON. See U(https://docs.github.com/en/rest/reference/repos#get-a-repository). 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 type: dict
''' '''

2
plugins/modules/gitlab_branch.py
View file

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

20
plugins/modules/gitlab_group_members.py
View file

@ -40,22 +40,22 @@ options:
gitlab_user: gitlab_user:
description: description:
- A username or a list of usernames to add to/remove from the GitLab group. - 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 type: list
elements: str elements: str
access_level: access_level:
description: description:
- The access level for the user. - 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.
- Mutually exclusive with I(gitlab_users_access). - Mutually exclusive with O(gitlab_users_access).
type: str type: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
gitlab_users_access: gitlab_users_access:
description: description:
- Provide a list of user to access level mappings. - 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. - 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). - Mutually exclusive with O(gitlab_user) and O(access_level).
- Use together with I(purge_users) to remove all users not specified here from the group. - Use together with O(purge_users) to remove all users not specified here from the group.
type: list type: list
elements: dict elements: dict
suboptions: suboptions:
@ -66,7 +66,7 @@ options:
access_level: access_level:
description: description:
- The access level for the user. - 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 type: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
required: true required: true
@ -74,16 +74,16 @@ options:
state: state:
description: description:
- State of the member in the group. - State of the member in the group.
- On C(present), it adds a user to a GitLab group. - On V(present), it adds a user to a GitLab group.
- On C(absent), it removes a user from a GitLab group. - On V(absent), it removes a user from a GitLab group.
choices: ['present', 'absent'] choices: ['present', 'absent']
default: 'present' default: 'present'
type: str type: str
purge_users: purge_users:
description: 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. If omitted do not purge orphaned members.
- Is only used when I(state=present). - Is only used when O(state=present).
type: list type: list
elements: str elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] 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. - 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. - 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, - 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: author:
- Florent Madiot (@scodeman) - Florent Madiot (@scodeman)
requirements: requirements:
@ -48,20 +48,20 @@ options:
type: str type: str
purge: purge:
description: 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 default: false
type: bool type: bool
vars: vars:
description: description:
- When the list element is a simple key-value pair, set masked and protected to false. - 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. have full control about whether a value should be masked, protected or both.
- Support for group variables requires GitLab >= 9.5. - Support for group variables requires GitLab >= 9.5.
- Support for environment_scope requires GitLab Premium >= 13.11. - Support for environment_scope requires GitLab Premium >= 13.11.
- Support for protected values requires GitLab >= 9.3. - Support for protected values requires GitLab >= 9.3.
- Support for masked values requires GitLab >= 11.10. - Support for masked values requires GitLab >= 11.10.
- A I(value) must be a string or a number. - A C(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 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. - 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)). See GitLab documentation on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)).
default: {} default: {}
@ -70,7 +70,7 @@ options:
version_added: 4.5.0 version_added: 4.5.0
description: description:
- A list of dictionaries that represents CI/CD variables. - 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: [] default: []
type: list type: list
elements: dict elements: dict
@ -83,7 +83,7 @@ options:
value: value:
description: description:
- The variable value. - The variable value.
- Required when I(state=present). - Required when O(state=present).
type: str type: str
masked: masked:
description: description:
@ -97,7 +97,7 @@ options:
default: false default: false
variable_type: variable_type:
description: 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 type: str
choices: [ "env_var", "file" ] choices: [ "env_var", "file" ]
default: env_var 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. - When a instance variable does exist, its value will be updated if the values are different.
- Support for instance variables requires GitLab >= 13.0. - Support for instance variables requires GitLab >= 13.0.
- Variables which are not mentioned in the modules options, but are present on the GitLab instance, - 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: author:
- Benedikt Braunger (@benibr) - Benedikt Braunger (@benibr)
requirements: requirements:
@ -45,7 +45,7 @@ options:
choices: ["present", "absent"] choices: ["present", "absent"]
purge: purge:
description: 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 default: false
type: bool type: bool
variables: variables:
@ -63,7 +63,7 @@ options:
value: value:
description: description:
- The variable value. - The variable value.
- Required when I(state=present). - Required when O(state=present).
type: str type: str
masked: masked:
description: description:
@ -77,7 +77,7 @@ options:
default: false default: false
variable_type: variable_type:
description: 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 type: str
choices: [ "env_var", "file" ] choices: [ "env_var", "file" ]
default: env_var 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 short_description: Creates/updates/deletes GitLab Projects
description: description:
- When the project does not exist in GitLab, it will be created. - 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. - When changes are made to the project, the project will be updated.
author: author:
- Werner Dijkerman (@dj-wasabi) - Werner Dijkerman (@dj-wasabi)
@ -84,9 +84,9 @@ options:
default: true default: true
visibility: visibility:
description: description:
- C(private) Project access must be granted explicitly for each user. - V(private) Project access must be granted explicitly for each user.
- C(internal) The project can be cloned by any logged in user. - V(internal) The project can be cloned by any logged in user.
- C(public) The project can be cloned without any authentication. - V(public) The project can be cloned without any authentication.
default: private default: private
type: str type: str
choices: ["private", "internal", "public"] choices: ["private", "internal", "public"]
@ -108,7 +108,7 @@ options:
merge_method: merge_method:
description: description:
- What requirements are placed upon merges. - 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 type: str
choices: ["ff", "merge", "rebase_merge"] choices: ["ff", "merge", "rebase_merge"]
default: merge default: merge
@ -176,78 +176,78 @@ options:
default_branch: default_branch:
description: description:
- Default branch name for a new project. - 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 type: str
version_added: "4.2.0" version_added: "4.2.0"
builds_access_level: builds_access_level:
description: description:
- C(private) means that repository CI/CD is allowed only to project members. - V(private) means that repository CI/CD is allowed only to project members.
- C(disabled) means that repository CI/CD is disabled. - V(disabled) means that repository CI/CD is disabled.
- C(enabled) means that repository CI/CD is enabled. - V(enabled) means that repository CI/CD is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.2.0" version_added: "6.2.0"
forking_access_level: forking_access_level:
description: description:
- C(private) means that repository forks is allowed only to project members. - V(private) means that repository forks is allowed only to project members.
- C(disabled) means that repository forks are disabled. - V(disabled) means that repository forks are disabled.
- C(enabled) means that repository forks are enabled. - V(enabled) means that repository forks are enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.2.0" version_added: "6.2.0"
container_registry_access_level: container_registry_access_level:
description: description:
- C(private) means that container registry is allowed only to project members. - V(private) means that container registry is allowed only to project members.
- C(disabled) means that container registry is disabled. - V(disabled) means that container registry is disabled.
- C(enabled) means that container registry is enabled. - V(enabled) means that container registry is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.2.0" version_added: "6.2.0"
releases_access_level: releases_access_level:
description: description:
- C(private) means that accessing release is allowed only to project members. - V(private) means that accessing release is allowed only to project members.
- C(disabled) means that accessing release is disabled. - V(disabled) means that accessing release is disabled.
- C(enabled) means that accessing release is enabled. - V(enabled) means that accessing release is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.4.0" version_added: "6.4.0"
environments_access_level: environments_access_level:
description: description:
- C(private) means that deployment to environment is allowed only to project members. - V(private) means that deployment to environment is allowed only to project members.
- C(disabled) means that deployment to environment is disabled. - V(disabled) means that deployment to environment is disabled.
- C(enabled) means that deployment to environment is enabled. - V(enabled) means that deployment to environment is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.4.0" version_added: "6.4.0"
feature_flags_access_level: feature_flags_access_level:
description: description:
- C(private) means that feature rollout is allowed only to project members. - V(private) means that feature rollout is allowed only to project members.
- C(disabled) means that feature rollout is disabled. - V(disabled) means that feature rollout is disabled.
- C(enabled) means that feature rollout is enabled. - V(enabled) means that feature rollout is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.4.0" version_added: "6.4.0"
infrastructure_access_level: infrastructure_access_level:
description: description:
- C(private) means that configuring infrastructure is allowed only to project members. - V(private) means that configuring infrastructure is allowed only to project members.
- C(disabled) means that configuring infrastructure is disabled. - V(disabled) means that configuring infrastructure is disabled.
- C(enabled) means that configuring infrastructure is enabled. - V(enabled) means that configuring infrastructure is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.4.0" version_added: "6.4.0"
monitor_access_level: monitor_access_level:
description: description:
- C(private) means that monitoring health is allowed only to project members. - V(private) means that monitoring health is allowed only to project members.
- C(disabled) means that monitoring health is disabled. - V(disabled) means that monitoring health is disabled.
- C(enabled) means that monitoring health is enabled. - V(enabled) means that monitoring health is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.4.0" version_added: "6.4.0"
security_and_compliance_access_level: security_and_compliance_access_level:
description: description:
- C(private) means that accessing security and complicance tab is allowed only to project members. - V(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. - V(disabled) means that accessing security and complicance tab is disabled.
- C(enabled) means that accessing security and complicance tab is enabled. - V(enabled) means that accessing security and complicance tab is enabled.
type: str type: str
choices: ["private", "disabled", "enabled"] choices: ["private", "disabled", "enabled"]
version_added: "6.4.0" version_added: "6.4.0"

6
plugins/modules/gitlab_project_badge.py
View file

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

18
plugins/modules/gitlab_project_members.py
View file

@ -42,21 +42,21 @@ options:
gitlab_user: gitlab_user:
description: description:
- A username or a list of usernames to add to/remove from the GitLab project. - 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 type: list
elements: str elements: str
access_level: access_level:
description: description:
- The access level for the user. - 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 type: str
choices: ['guest', 'reporter', 'developer', 'maintainer'] choices: ['guest', 'reporter', 'developer', 'maintainer']
gitlab_users_access: gitlab_users_access:
description: description:
- Provide a list of user to access level mappings. - 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. - 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). - Mutually exclusive with O(gitlab_user) and O(access_level).
- Use together with I(purge_users) to remove all users not specified here from the project. - Use together with O(purge_users) to remove all users not specified here from the project.
type: list type: list
elements: dict elements: dict
suboptions: suboptions:
@ -67,7 +67,7 @@ options:
access_level: access_level:
description: description:
- The access level for the user. - 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 type: str
choices: ['guest', 'reporter', 'developer', 'maintainer'] choices: ['guest', 'reporter', 'developer', 'maintainer']
required: true required: true
@ -75,16 +75,16 @@ options:
state: state:
description: description:
- State of the member in the project. - State of the member in the project.
- On C(present), it adds a user to a GitLab project. - On V(present), it adds a user to a GitLab project.
- On C(absent), it removes a user from a GitLab project. - On V(absent), it removes a user from a GitLab project.
choices: ['present', 'absent'] choices: ['present', 'absent']
default: 'present' default: 'present'
type: str type: str
purge_users: purge_users:
description: 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. If omitted do not purge orphaned members.
- Is only used when I(state=present). - Is only used when O(state=present).
type: list type: list
elements: str elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer'] 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 not exist, it will be created.
- When a project variable does exist, its value will be updated when the values are different. - 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, - 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: author:
- "Markus Bergholz (@markuman)" - "Markus Bergholz (@markuman)"
requirements: requirements:
@ -52,15 +52,15 @@ options:
vars: vars:
description: 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 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. have full control about whether a value should be masked, protected or both.
- Support for protected values requires GitLab >= 9.3. - Support for protected values requires GitLab >= 9.3.
- Support for masked values requires GitLab >= 11.10. - Support for masked values requires GitLab >= 11.10.
- Support for environment_scope requires GitLab Premium >= 13.11. - Support for environment_scope requires GitLab Premium >= 13.11.
- Support for variable_type requires GitLab >= 11.11. - Support for variable_type requires GitLab >= 11.11.
- A I(value) must be a string or a number. - A C(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 C(variable_type) must be a string with either V(env_var), which is the default, or V(file).
- Field I(environment_scope) must be a string defined by scope environment. - 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. - 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). See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).
default: {} default: {}
@ -69,7 +69,7 @@ options:
version_added: 4.4.0 version_added: 4.4.0
description: description:
- A list of dictionaries that represents CI/CD variables. - 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: [] default: []
type: list type: list
elements: dict elements: dict
@ -82,7 +82,7 @@ options:
value: value:
description: description:
- The variable value. - The variable value.
- Required when I(state=present). - Required when O(state=present).
type: str type: str
masked: masked:
description: description:
@ -98,15 +98,15 @@ options:
default: false default: false
variable_type: variable_type:
description: 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)).
- Support for I(variable_type) requires GitLab >= 11.11. - Support for O(variables[].variable_type) requires GitLab >= 11.11.
type: str type: str
choices: ["env_var", "file"] choices: ["env_var", "file"]
default: env_var default: env_var
environment_scope: environment_scope:
description: description:
- The scope for the variable. - 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 type: str
default: '*' 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. 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/). It can be found at U(https://$GITLAB_URL/admin/runners/).
notes: 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. - Runners need to have unique descriptions.
author: author:
- Samy Coenen (@SamyCoenen) - Samy Coenen (@SamyCoenen)
@ -47,14 +47,14 @@ options:
group: group:
description: description:
- ID or full path of the group in the form group/subgroup. - 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 type: str
version_added: '6.5.0' version_added: '6.5.0'
project: project:
description: description:
- ID or full path of the project in the form of group/name. - 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 O(owned) since community.general 4.5.0.
- Mutually exclusive with I(group). - Mutually exclusive with O(group).
type: str type: str
version_added: '3.7.0' version_added: '3.7.0'
description: description:
@ -74,13 +74,13 @@ options:
registration_token: registration_token:
description: description:
- The registration token is used to register new runners. - The registration token is used to register new runners.
- Required if I(state) is C(present). - Required if O(state=present).
type: str type: str
owned: owned:
description: description:
- Searches only runners available to the user when searching for existing, when false admin token required. - 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 O(project) since community.general 4.5.0.
- Mutually exclusive with I(group). - Mutually exclusive with O(group).
default: false default: false
type: bool type: bool
version_added: 2.0.0 version_added: 2.0.0
@ -99,12 +99,12 @@ options:
access_level: access_level:
description: description:
- Determines if a runner can pick up jobs only from protected branches. - 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. 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 V(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. - If set to V(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. - 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 C(not_protected) 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. on creation, and the value set will not be changed on any updates.
required: false required: false
choices: ["not_protected", "ref_protected"] choices: ["not_protected", "ref_protected"]
@ -112,9 +112,9 @@ options:
access_level_on_creation: access_level_on_creation:
description: description:
- Whether the runner should be registered with an access level or not. - 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 V(true), the value of O(access_level) is used for runner registration.
- If set to C(false), GitLab registers the runner with the default access level. - If set to V(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). - The default of this option changed to V(true) in community.general 7.0.0. Before, it was V(false).
required: false required: false
default: true default: true
type: bool type: bool

10
plugins/modules/gitlab_user.py
View file

@ -45,7 +45,7 @@ options:
name: name:
description: description:
- Name of the user you want to create. - 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 type: str
username: username:
description: description:
@ -66,7 +66,7 @@ options:
email: email:
description: description:
- The email that belongs to the user. - 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 type: str
sshkey_name: sshkey_name:
description: description:
@ -123,7 +123,7 @@ options:
identities: identities:
description: description:
- List of identities to be added/updated for this user. - 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 type: list
elements: dict elements: dict
suboptions: suboptions:
@ -139,8 +139,8 @@ options:
overwrite_identities: overwrite_identities:
description: description:
- Overwrite identities with identities added in this module. - 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 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 I(identities). To remove all identities, provide an empty list. - This is only done if a list is provided for O(identities). To remove all identities, provide an empty list.
type: bool type: bool
default: false default: false
version_added: 3.3.0 version_added: 3.3.0

2
plugins/modules/grove.py
View file

@ -39,7 +39,7 @@ options:
type: str type: str
description: description:
- Message content. - 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 required: true
url: url:
type: str type: str