From 2ed82e0318b57d9a6f25466a5dc5d4196a23a0c1 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Jun 2023 15:46:44 +0200 Subject: [PATCH] Use semantic markup (modules d-g) (#6672) * Use semantic markup. * 'ignore:' is no longer needed. * E() now works better. --- plugins/modules/datadog_monitor.py | 14 ++--- plugins/modules/deploy_helper.py | 47 +++++++------- plugins/modules/dimensiondata_network.py | 2 +- plugins/modules/dimensiondata_vlan.py | 8 +-- plugins/modules/discord.py | 6 +- plugins/modules/django_manage.py | 70 ++++++++++----------- plugins/modules/dnf_versionlock.py | 16 ++--- plugins/modules/dnsimple.py | 4 +- plugins/modules/dnsimple_info.py | 6 +- plugins/modules/dpkg_divert.py | 26 ++++---- plugins/modules/easy_install.py | 18 +++--- plugins/modules/etcd3.py | 8 +-- plugins/modules/facter.py | 2 +- plugins/modules/filesize.py | 38 +++++------ plugins/modules/filesystem.py | 28 ++++----- plugins/modules/flatpak.py | 14 ++--- plugins/modules/flatpak_remote.py | 22 +++---- plugins/modules/gandi_livedns.py | 4 +- plugins/modules/gconftool2.py | 16 ++--- plugins/modules/git_config.py | 20 +++--- plugins/modules/github_deploy_key.py | 10 +-- plugins/modules/github_key.py | 8 +-- plugins/modules/github_repo.py | 28 ++++----- plugins/modules/gitlab_branch.py | 2 +- plugins/modules/gitlab_group_members.py | 20 +++--- plugins/modules/gitlab_group_variable.py | 16 ++--- plugins/modules/gitlab_instance_variable.py | 8 +-- plugins/modules/gitlab_project.py | 66 +++++++++---------- plugins/modules/gitlab_project_badge.py | 6 +- plugins/modules/gitlab_project_members.py | 18 +++--- plugins/modules/gitlab_project_variable.py | 20 +++--- plugins/modules/gitlab_runner.py | 30 ++++----- plugins/modules/gitlab_user.py | 10 +-- plugins/modules/grove.py | 2 +- 34 files changed, 307 insertions(+), 306 deletions(-) diff --git a/plugins/modules/datadog_monitor.py b/plugins/modules/datadog_monitor.py index d1ad288ccc..75ae8c2332 100644 --- a/plugins/modules/datadog_monitor.py +++ b/plugins/modules/datadog_monitor.py @@ -16,7 +16,6 @@ short_description: Manages Datadog monitors description: - Manages monitors within Datadog. - Options as described on https://docs.datadoghq.com/api/. - - The type C(event-v2) was added in community.general 4.8.0. author: Sebastian Kornehl (@skornehl) requirements: [datadog] extends_documentation_fragment: @@ -34,8 +33,8 @@ options: type: str api_host: description: - - The URL to the Datadog API. Default value is C(https://api.datadoghq.com). - - This value can also be set with the C(DATADOG_HOST) environment variable. + - The URL to the Datadog API. Default value is V(https://api.datadoghq.com). + - This value can also be set with the E(DATADOG_HOST) environment variable. required: false type: str version_added: '0.2.0' @@ -59,8 +58,9 @@ options: type: description: - The type of the monitor. - - The types C(query alert), C(trace-analytics alert) and C(rum alert) were added in community.general 2.1.0. - - The type C(composite) was added in community.general 3.4.0. + - The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0. + - The type V(composite) was added in community.general 3.4.0. + - The type V(event-v2 alert) was added in community.general 4.8.0. choices: - metric alert - service check @@ -117,7 +117,7 @@ options: escalation_message: description: - A message to include with a re-notification. Supports the '@username' notification we allow elsewhere. - - Not applicable if I(renotify_interval=None). + - Not applicable if O(renotify_interval=none). type: str notify_audit: description: @@ -130,7 +130,7 @@ options: - A dictionary of thresholds by status. - Only available for service checks and metric alerts. - Because each of them can have multiple thresholds, we do not define them directly in the query. - - "If not specified, it defaults to: C({'ok': 1, 'critical': 1, 'warning': 1})." + - "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})." locked: description: - Whether changes to this monitor should be restricted to the creator or admins. diff --git a/plugins/modules/deploy_helper.py b/plugins/modules/deploy_helper.py index f0246cae63..b47ed82540 100644 --- a/plugins/modules/deploy_helper.py +++ b/plugins/modules/deploy_helper.py @@ -20,8 +20,9 @@ description: - The Deploy Helper manages some of the steps common in deploying software. It creates a folder structure, manages a symlink for the current release and cleans up old releases. - - "Running it with the I(state=query) or I(state=present) will return the C(deploy_helper) fact. - C(project_path), whatever you set in the I(path) parameter, + # TODO: convert below to RETURN documentation! + - "Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. + C(project_path), whatever you set in the O(path) parameter, C(current_path), the path to the symlink that points to the active release, C(releases_path), the path to the folder to keep releases in, C(shared_path), the path to the folder to keep shared resources in, @@ -50,33 +51,33 @@ options: type: str description: - The state of the project. - C(query) will only gather facts, - C(present) will create the project I(root) folder, and in it the I(releases) and I(shared) folders, - C(finalize) will remove the unfinished_filename file, create a symlink to the newly - deployed release and optionally clean old releases, - C(clean) will remove failed & old releases, - C(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with I(state=absent)). + - V(query) will only gather facts. + - V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders. + - V(finalize) will remove the unfinished_filename file, create a symlink to the newly + deployed release and optionally clean old releases. + - V(clean) will remove failed & old releases. + - V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)). choices: [ present, finalize, absent, clean, query ] default: present release: type: str description: - - The release version that is being deployed. Defaults to a timestamp format %Y%m%d%H%M%S (i.e. '20141119223359'). - This parameter is optional during I(state=present), but needs to be set explicitly for I(state=finalize). - You can use the generated fact I(release={{ deploy_helper.new_release }}). + - The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)). + This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). + You can use the generated fact C(release={{ deploy_helper.new_release }}). releases_path: type: str description: - - The name of the folder that will hold the releases. This can be relative to I(path) or absolute. + - The name of the folder that will hold the releases. This can be relative to O(path) or absolute. Returned in the C(deploy_helper.releases_path) fact. default: releases shared_path: type: path description: - - The name of the folder that will hold the shared resources. This can be relative to I(path) or absolute. + - The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. If this is set to an empty string, no shared folder will be created. Returned in the C(deploy_helper.shared_path) fact. default: shared @@ -84,38 +85,38 @@ options: current_path: type: path description: - - The name of the symlink that is created when the deploy is finalized. Used in I(finalize) and I(clean). + - The name of the symlink that is created when the deploy is finalized. Used in O(state=finalize) and O(state=clean). Returned in the C(deploy_helper.current_path) fact. default: current unfinished_filename: type: str description: - - The name of the file that indicates a deploy has not finished. All folders in the I(releases_path) that - contain this file will be deleted on I(state=finalize) with I(clean=True), or I(state=clean). This file is - automatically deleted from the I(new_release_path) during I(state=finalize). + - The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that + contain this file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is + automatically deleted from the C(new_release_path) during O(state=finalize). default: DEPLOY_UNFINISHED clean: description: - - Whether to run the clean procedure in case of I(state=finalize). + - Whether to run the clean procedure in case of O(state=finalize). type: bool default: true keep_releases: type: int description: - - The number of old releases to keep when cleaning. Used in I(finalize) and I(clean). Any unfinished builds + - The number of old releases to keep when cleaning. Used in O(state=finalize) and O(state=clean). Any unfinished builds will be deleted first, so only correct releases will count. The current version will not count. default: 5 notes: - - Facts are only returned for I(state=query) and I(state=present). If you use both, you should pass any overridden + - Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden parameters to both calls, otherwise the second call will overwrite the facts of the first one. - - When using I(state=clean), the releases are ordered by I(creation date). You should be able to switch to a + - When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a new naming strategy without problems. - - Because of the default behaviour of generating the I(new_release) fact, this module will not be idempotent - unless you pass your own release name with I(release). Due to the nature of deploying software, this should not + - Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent + unless you pass your own release name with O(release). Due to the nature of deploying software, this should not be much of a problem. extends_documentation_fragment: - ansible.builtin.files diff --git a/plugins/modules/dimensiondata_network.py b/plugins/modules/dimensiondata_network.py index 8c1469063c..cfb7d61cd9 100644 --- a/plugins/modules/dimensiondata_network.py +++ b/plugins/modules/dimensiondata_network.py @@ -84,7 +84,7 @@ EXAMPLES = ''' RETURN = ''' network: description: Dictionary describing the network. - returned: On success when I(state=present). + returned: On success when O(state=present). type: complex contains: id: diff --git a/plugins/modules/dimensiondata_vlan.py b/plugins/modules/dimensiondata_vlan.py index 7d83ddc696..9d129f3dea 100644 --- a/plugins/modules/dimensiondata_vlan.py +++ b/plugins/modules/dimensiondata_vlan.py @@ -51,20 +51,20 @@ options: private_ipv4_prefix_size: description: - The size of the IPv4 address space, e.g 24. - - Required, if C(private_ipv4_base_address) is specified. + - Required, if O(private_ipv4_base_address) is specified. type: int default: 0 state: description: - The desired state for the target VLAN. - - C(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist). + - V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist). choices: [present, absent, readonly] default: present type: str allow_expand: description: - Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses. - - If C(False), the module will fail under these conditions. + - If V(false), the module will fail under these conditions. - This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible). type: bool default: false @@ -105,7 +105,7 @@ EXAMPLES = ''' RETURN = ''' vlan: description: Dictionary describing the VLAN. - returned: On success when I(state) is 'present' + returned: On success when O(state=present) type: complex contains: id: diff --git a/plugins/modules/discord.py b/plugins/modules/discord.py index 8b5391d44b..130649f076 100644 --- a/plugins/modules/discord.py +++ b/plugins/modules/discord.py @@ -43,7 +43,7 @@ options: content: description: - Content of the message to the Discord channel. - - At least one of I(content) and I(embeds) must be specified. + - At least one of O(content) and O(embeds) must be specified. type: str username: description: @@ -55,7 +55,7 @@ options: type: str tts: description: - - Set this to C(true) if this is a TTS (Text to Speech) message. + - Set this to V(true) if this is a TTS (Text to Speech) message. type: bool default: false embeds: @@ -63,7 +63,7 @@ options: - Send messages as Embeds to the Discord channel. - Embeds can have a colored border, embedded images, text fields and more. - "Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object)" - - At least one of I(content) and I(embeds) must be specified. + - At least one of O(content) and O(embeds) must be specified. type: list elements: dict ''' diff --git a/plugins/modules/django_manage.py b/plugins/modules/django_manage.py index 537cf0fa74..e2de1db3e2 100644 --- a/plugins/modules/django_manage.py +++ b/plugins/modules/django_manage.py @@ -16,7 +16,7 @@ module: django_manage short_description: Manages a Django application description: - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the - I(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation. + O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation. extends_documentation_fragment: - community.general.attributes attributes: @@ -29,20 +29,20 @@ options: description: - The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation. - > - C(cleanup) - clean up old data from the database (deprecated in Django 1.5). This parameter will be - removed in community.general 9.0.0. Use C(clearsessions) instead. - - C(collectstatic) - Collects the static files into C(STATIC_ROOT). - - C(createcachetable) - Creates the cache tables for use with the database cache backend. - - C(flush) - Removes all data from the database. - - C(loaddata) - Searches for and loads the contents of the named I(fixtures) into the database. - - C(migrate) - Synchronizes the database state with models and migrations. + V(cleanup) - clean up old data from the database (deprecated in Django 1.5). This parameter will be + removed in community.general 9.0.0. Use V(clearsessions) instead. + - V(collectstatic) - Collects the static files into C(STATIC_ROOT). + - V(createcachetable) - Creates the cache tables for use with the database cache backend. + - V(flush) - Removes all data from the database. + - V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database. + - V(migrate) - Synchronizes the database state with models and migrations. - > - C(syncdb) - Synchronizes the database state with models and migrations (deprecated in Django 1.7). - This parameter will be removed in community.general 9.0.0. Use C(migrate) instead. - - C(test) - Runs tests for all installed apps. + V(syncdb) - Synchronizes the database state with models and migrations (deprecated in Django 1.7). + This parameter will be removed in community.general 9.0.0. Use V(migrate) instead. + - V(test) - Runs tests for all installed apps. - > - C(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be - removed in community.general 9.0.0. Use C(check) instead. + V(validate) - Validates all installed models (deprecated in Django 1.7). This parameter will be + removed in community.general 9.0.0. Use V(check) instead. - Other commands can be entered, but will fail if they are unknown to Django. Other commands that may prompt for user input should be run with the C(--noinput) flag. type: str @@ -55,14 +55,14 @@ options: aliases: [app_path, chdir] settings: description: - - The Python path to the application's settings module, such as C(myapp.settings). + - The Python path to the application's settings module, such as V(myapp.settings). type: path required: false pythonpath: description: - A directory to add to the Python path. Typically used to include the settings module if it is located external to the application directory. - - This would be equivalent to adding I(pythonpath)'s value to the C(PYTHONPATH) environment variable. + - This would be equivalent to adding O(pythonpath)'s value to the C(PYTHONPATH) environment variable. type: path required: false aliases: [python_path] @@ -73,54 +73,54 @@ options: aliases: [virtual_env] apps: description: - - A list of space-delimited apps to target. Used by the C(test) command. + - A list of space-delimited apps to target. Used by the V(test) command. type: str required: false cache_table: description: - - The name of the table used for database-backed caching. Used by the C(createcachetable) command. + - The name of the table used for database-backed caching. Used by the V(createcachetable) command. type: str required: false clear: description: - Clear the existing files before trying to copy or link the original file. - - Used only with the C(collectstatic) command. The C(--noinput) argument will be added automatically. + - Used only with the V(collectstatic) command. The C(--noinput) argument will be added automatically. required: false default: false type: bool database: description: - - The database to target. Used by the C(createcachetable), C(flush), C(loaddata), C(syncdb), - and C(migrate) commands. + - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), + and V(migrate) commands. type: str required: false failfast: description: - - Fail the command immediately if a test fails. Used by the C(test) command. + - Fail the command immediately if a test fails. Used by the V(test) command. required: false default: false type: bool aliases: [fail_fast] fixtures: description: - - A space-delimited list of fixture file names to load in the database. B(Required) by the C(loaddata) command. + - A space-delimited list of fixture file names to load in the database. B(Required) by the V(loaddata) command. type: str required: false skip: description: - - Will skip over out-of-order missing migrations, you can only use this parameter with C(migrate) command. + - Will skip over out-of-order missing migrations, you can only use this parameter with V(migrate) command. required: false type: bool merge: description: - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this - parameter with C(migrate) command. + parameter with V(migrate) command. required: false type: bool link: description: - Will create links to the files instead of copying them, you can only use this parameter with - C(collectstatic) command. + V(collectstatic) command. required: false type: bool testrunner: @@ -133,9 +133,9 @@ options: ack_venv_creation_deprecation: description: - >- - When a I(virtualenv) is set but the virtual environment does not exist, the current behavior is + When a O(virtualenv) is set but the virtual environment does not exist, the current behavior is to create a new virtual environment. That behavior is deprecated and if that case happens it will - generate a deprecation warning. Set this flag to C(true) to suppress the deprecation warning. + generate a deprecation warning. Set this flag to V(true) to suppress the deprecation warning. - Please note that you will receive no further warning about this being removed until the module will start failing in such cases from community.general 9.0.0 on. type: bool @@ -146,19 +146,19 @@ notes: B(ATTENTION - DEPRECATION): Support for Django releases older than 4.1 will be removed in community.general version 9.0.0 (estimated to be released in May 2024). Please notice that Django 4.1 requires Python 3.8 or greater. - - C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the I(virtualenv) parameter + - C(virtualenv) (U(http://www.virtualenv.org)) must be installed on the remote host if the O(virtualenv) parameter is specified. This requirement is deprecated and will be removed in community.general version 9.0.0. - - This module will create a virtualenv if the I(virtualenv) parameter is specified and a virtual environment does not already + - This module will create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment does not already exist at the given location. This behavior is deprecated and will be removed in community.general version 9.0.0. - - The parameter I(virtualenv) will remain in use, but it will require the specified virtualenv to exist. + - The parameter O(virtualenv) will remain in use, but it will require the specified virtualenv to exist. The recommended way to create one in Ansible is by using M(ansible.builtin.pip). - - This module assumes English error messages for the C(createcachetable) command to detect table existence, + - This module assumes English error messages for the V(createcachetable) command to detect table existence, unfortunately. - - To be able to use the C(migrate) command with django versions < 1.7, you must have C(south) installed and added + - To be able to use the V(migrate) command with django versions < 1.7, you must have C(south) installed and added as an app in your settings. - - To be able to use the C(collectstatic) command, you must have enabled staticfiles in your settings. - - Your C(manage.py) application must be executable (rwxr-xr-x), and must have a valid shebang, - i.e. C(#!/usr/bin/env python), for invoking the appropriate Python interpreter. + - To be able to use the V(collectstatic) command, you must have enabled staticfiles in your settings. + - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, + for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter. seealso: - name: django-admin and manage.py Reference description: Reference for C(django-admin) or C(manage.py) commands. diff --git a/plugins/modules/dnf_versionlock.py b/plugins/modules/dnf_versionlock.py index fac3ad78d4..3fcf132eaf 100644 --- a/plugins/modules/dnf_versionlock.py +++ b/plugins/modules/dnf_versionlock.py @@ -38,7 +38,7 @@ options: description: - Package name spec to add or exclude to or delete from the C(locklist) using the format expected by the C(dnf repoquery) command. - - This parameter is mutually exclusive with I(state=clean). + - This parameter is mutually exclusive with O(state=clean). type: list required: false elements: str @@ -52,19 +52,19 @@ options: default: false state: description: - - Whether to add (C(present) or C(excluded)) to or remove (C(absent) or - C(clean)) from the C(locklist). - - C(present) will add a package name spec to the C(locklist). If there is a + - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or + V(clean)) from the C(locklist). + - V(present) will add a package name spec to the C(locklist). If there is a installed package that matches, then only that version will be added. Otherwise, all available package versions will be added. - - C(excluded) will add a package name spec as excluded to the + - V(excluded) will add a package name spec as excluded to the C(locklist). It means that packages represented by the package name spec will be excluded from transaction operations. All available package versions will be added. - - C(absent) will delete entries in the C(locklist) that match the + - V(absent) will delete entries in the C(locklist) that match the package name spec. - - C(clean) will delete all entries in the C(locklist). This option is - mutually exclusive with C(name). + - V(clean) will delete all entries in the C(locklist). This option is + mutually exclusive with O(name). choices: [ 'absent', 'clean', 'excluded', 'present' ] type: str default: present diff --git a/plugins/modules/dnsimple.py b/plugins/modules/dnsimple.py index df41f73a69..363b645f80 100644 --- a/plugins/modules/dnsimple.py +++ b/plugins/modules/dnsimple.py @@ -32,7 +32,7 @@ options: type: str account_api_token: description: - - Account API token. See I(account_email) for more information. + - Account API token. See O(account_email) for more information. type: str domain: description: @@ -77,7 +77,7 @@ options: solo: description: - Whether the record should be the only one for that record type and record name. - - Only use with C(state) is set to C(present) on a record. + - Only use with O(state) is set to V(present) on a record. type: 'bool' default: false sandbox: diff --git a/plugins/modules/dnsimple_info.py b/plugins/modules/dnsimple_info.py index 796ff8689c..46c2877f73 100644 --- a/plugins/modules/dnsimple_info.py +++ b/plugins/modules/dnsimple_info.py @@ -83,7 +83,7 @@ dnsimple_domain_info: description: Returns a list of dictionaries of all domains associated with the supplied account ID. type: list elements: dict - returned: success when I(name) is not specified + returned: success when O(name) is not specified sample: - account_id: 1234 created_at: '2021-10-16T21:25:42Z' @@ -120,7 +120,7 @@ dnsimple_records_info: description: Returns a list of dictionaries with all records for the domain supplied. type: list elements: dict - returned: success when I(name) is specified, but I(record) is not + returned: success when O(name) is specified, but O(record) is not sample: - content: ns1.dnsimple.com admin.dnsimple.com created_at: '2021-10-16T19:07:34Z' @@ -174,7 +174,7 @@ dnsimple_records_info: type: str dnsimple_record_info: description: Returns a list of dictionaries that match the record supplied. - returned: success when I(name) and I(record) are specified + returned: success when O(name) and O(record) are specified type: list elements: dict sample: diff --git a/plugins/modules/dpkg_divert.py b/plugins/modules/dpkg_divert.py index 4a1651f517..5f0d924fe2 100644 --- a/plugins/modules/dpkg_divert.py +++ b/plugins/modules/dpkg_divert.py @@ -20,13 +20,13 @@ description: - A diversion is for C(dpkg) the knowledge that only a given package (or the local administrator) is allowed to install a file at a given location. Other packages shipping their own version of this file will - be forced to I(divert) it, i.e. to install it at another location. It + be forced to O(divert) it, that is to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing its overwrite at package upgrade. - This module manages diversions of debian packages files using the C(dpkg-divert) commandline tool. It can either create or remove a diversion for a given file, but also update an existing diversion - to modify its I(holder) and/or its I(divert) location. + to modify its O(holder) and/or its O(divert) location. extends_documentation_fragment: - community.general.attributes attributes: @@ -39,14 +39,14 @@ options: description: - The original and absolute path of the file to be diverted or undiverted. This path is unique, i.e. it is not possible to get - two diversions for the same I(path). + two diversions for the same O(path). required: true type: path state: description: - - When I(state=absent), remove the diversion of the specified - I(path); when I(state=present), create the diversion if it does - not exist, or update its package I(holder) or I(divert) location, + - When O(state=absent), remove the diversion of the specified + O(path); when O(state=present), create the diversion if it does + not exist, or update its package O(holder) or O(divert) location, if it already exists. type: str default: present @@ -59,31 +59,31 @@ options: - The actual package does not have to be installed or even to exist for its name to be valid. If not specified, the diversion is hold by 'LOCAL', that is reserved by/for dpkg for local diversions. - - This parameter is ignored when I(state=absent). + - This parameter is ignored when O(state=absent). type: str divert: description: - The location where the versions of file will be diverted. - Default is to add suffix C(.distrib) to the file path. - - This parameter is ignored when I(state=absent). + - This parameter is ignored when O(state=absent). type: path rename: description: - - Actually move the file aside (when I(state=present)) or back (when - I(state=absent)), but only when changing the state of the diversion. + - Actually move the file aside (when O(state=present)) or back (when + O(state=absent)), but only when changing the state of the diversion. This parameter has no effect when attempting to add a diversion that already exists or when removing an unexisting one. - - Unless I(force=true), renaming fails if the destination file already + - Unless O(force=true), renaming fails if the destination file already exists (this lock being a dpkg-divert feature, and bypassing it being a module feature). type: bool default: false force: description: - - When I(rename=true) and I(force=true), renaming is performed even if + - When O(rename=true) and O(force=true), renaming is performed even if the target of the renaming exists, i.e. the existing contents of the file at this location will be lost. - - This parameter is ignored when I(rename=false). + - This parameter is ignored when O(rename=false). type: bool default: false requirements: diff --git a/plugins/modules/easy_install.py b/plugins/modules/easy_install.py index 564493180a..2e8fc2f4f0 100644 --- a/plugins/modules/easy_install.py +++ b/plugins/modules/easy_install.py @@ -14,7 +14,7 @@ DOCUMENTATION = ''' module: easy_install short_description: Installs Python libraries description: - - Installs Python libraries, optionally in a I(virtualenv) + - Installs Python libraries, optionally in a C(virtualenv) extends_documentation_fragment: - community.general.attributes attributes: @@ -26,13 +26,13 @@ options: name: type: str description: - - A Python library name + - A Python library name. required: true virtualenv: type: str description: - - an optional I(virtualenv) directory path to install into. If the - I(virtualenv) does not exist, it is created automatically + - An optional O(virtualenv) directory path to install into. If the + O(virtualenv) does not exist, it is created automatically. virtualenv_site_packages: description: - Whether the virtual environment will inherit packages from the @@ -46,21 +46,21 @@ options: type: str description: - The command to create the virtual environment with. For example - C(pyvenv), C(virtualenv), C(virtualenv2). + V(pyvenv), V(virtualenv), V(virtualenv2). default: virtualenv executable: type: str description: - The explicit executable or a pathname to the executable to be used to run easy_install for a specific version of Python installed in the - system. For example C(easy_install-3.3), if there are both Python 2.7 + system. For example V(easy_install-3.3), if there are both Python 2.7 and 3.3 installations in the system and you want to run easy_install for the Python 3.3 installation. default: easy_install state: type: str description: - - The desired state of the library. C(latest) ensures that the latest version is installed. + - The desired state of the library. V(latest) ensures that the latest version is installed. choices: [present, latest] default: present notes: @@ -68,8 +68,8 @@ notes: libraries. Thus this module is not able to remove libraries. It is generally recommended to use the M(ansible.builtin.pip) module which you can first install using M(community.general.easy_install). - - Also note that I(virtualenv) must be installed on the remote host if the - C(virtualenv) parameter is specified. + - Also note that C(virtualenv) must be installed on the remote host if the + O(virtualenv) parameter is specified. requirements: [ "virtualenv" ] author: "Matt Wright (@mattupstate)" ''' diff --git a/plugins/modules/etcd3.py b/plugins/modules/etcd3.py index 9cd0274068..2fdc3f2f83 100644 --- a/plugins/modules/etcd3.py +++ b/plugins/modules/etcd3.py @@ -61,22 +61,22 @@ options: type: str description: - The password to use for authentication. - - Required if I(user) is defined. + - Required if O(user) is defined. ca_cert: type: path description: - The Certificate Authority to use to verify the etcd host. - - Required if I(client_cert) and I(client_key) are defined. + - Required if O(client_cert) and O(client_key) are defined. client_cert: type: path description: - PEM formatted certificate chain file to be used for SSL client authentication. - - Required if I(client_key) is defined. + - Required if O(client_key) is defined. client_key: type: path description: - PEM formatted file that contains your private key to be used for SSL client authentication. - - Required if I(client_cert) is defined. + - Required if O(client_cert) is defined. timeout: type: int description: diff --git a/plugins/modules/facter.py b/plugins/modules/facter.py index e7cf52e203..87017246ae 100644 --- a/plugins/modules/facter.py +++ b/plugins/modules/facter.py @@ -11,7 +11,7 @@ __metaclass__ = type DOCUMENTATION = ''' --- module: facter -short_description: Runs the discovery program I(facter) on the remote system +short_description: Runs the discovery program C(facter) on the remote system description: - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning diff --git a/plugins/modules/filesize.py b/plugins/modules/filesize.py index b3eb90d611..83de682883 100644 --- a/plugins/modules/filesize.py +++ b/plugins/modules/filesize.py @@ -41,20 +41,20 @@ options: description: - Requested size of the file. - The value is a number (either C(int) or C(float)) optionally followed - by a multiplicative suffix, that can be one of C(B) (bytes), C(KB) or - C(kB) (= 1000B), C(MB) or C(mB) (= 1000kB), C(GB) or C(gB) (= 1000MB), - and so on for C(T), C(P), C(E), C(Z) and C(Y); or alternatively one of - C(K), C(k) or C(KiB) (= 1024B); C(M), C(m) or C(MiB) (= 1024KiB); - C(G), C(g) or C(GiB) (= 1024MiB); and so on. + by a multiplicative suffix, that can be one of V(B) (bytes), V(KB) or + V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), + and so on for V(T), V(P), V(E), V(Z) and V(Y); or alternatively one of + V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB); + V(G), V(g) or V(GiB) (= 1024MiB); and so on. - If the multiplicative suffix is not provided, the value is treated as - an integer number of blocks of I(blocksize) bytes each (float values + an integer number of blocks of O(blocksize) bytes each (float values are rounded to the closest integer). - - When the I(size) value is equal to the current file size, does nothing. - - When the I(size) value is bigger than the current file size, bytes from - I(source) (if I(sparse) is not C(false)) are appended to the file + - When the O(size) value is equal to the current file size, does nothing. + - When the O(size) value is bigger than the current file size, bytes from + O(source) (if O(sparse) is not V(false)) are appended to the file without truncating it, in other words, without modifying the existing bytes of the file. - - When the I(size) value is smaller than the current file size, it is + - When the O(size) value is smaller than the current file size, it is truncated to the requested value without modifying bytes before this value. - That means that a file of any arbitrary size can be grown to any other @@ -65,24 +65,24 @@ options: blocksize: description: - Size of blocks, in bytes if not followed by a multiplicative suffix. - - The numeric value (before the unit) C(MUST) be an integer (or a C(float) + - The numeric value (before the unit) B(MUST) be an integer (or a C(float) if it equals an integer). - If not set, the size of blocks is guessed from the OS and commonly - results in C(512) or C(4096) bytes, that is used internally by the - module or when I(size) has no unit. + results in V(512) or V(4096) bytes, that is used internally by the + module or when O(size) has no unit. type: raw source: description: - Device or file that provides input data to provision the file. - - This parameter is ignored when I(sparse=true). + - This parameter is ignored when O(sparse=true). type: path default: /dev/zero force: description: - Whether or not to overwrite the file if it exists, in other words, to - truncate it from 0. When C(true), the module is not idempotent, that - means it always reports I(changed=true). - - I(force=true) and I(sparse=true) are mutually exclusive. + truncate it from 0. When V(true), the module is not idempotent, that + means it always reports C(changed=true). + - O(force=true) and O(sparse=true) are mutually exclusive. type: bool default: false sparse: @@ -91,7 +91,7 @@ options: - This option is effective only on newly created files, or when growing a file, only for the bytes to append. - This option is not supported on OSes or filesystems not supporting sparse files. - - I(force=true) and I(sparse=true) are mutually exclusive. + - O(force=true) and O(sparse=true) are mutually exclusive. type: bool default: false unsafe_writes: @@ -206,7 +206,7 @@ filesize: type: int sample: 1024 bytes: - description: Size of the file, in bytes, as the product of C(blocks) and C(blocksize). + description: Size of the file, in bytes, as the product of RV(filesize.blocks) and RV(filesize.blocksize). type: int sample: 512000 iec: diff --git a/plugins/modules/filesystem.py b/plugins/modules/filesystem.py index 0e6b815b4e..a336818abf 100644 --- a/plugins/modules/filesystem.py +++ b/plugins/modules/filesystem.py @@ -29,12 +29,12 @@ attributes: options: state: description: - - If I(state=present), the filesystem is created if it doesn't already - exist, that is the default behaviour if I(state) is omitted. - - If I(state=absent), filesystem signatures on I(dev) are wiped if it + - If O(state=present), the filesystem is created if it doesn't already + exist, that is the default behaviour if O(state) is omitted. + - If O(state=absent), filesystem signatures on O(dev) are wiped if it contains a filesystem (as known by C(blkid)). - - When I(state=absent), all other options but I(dev) are ignored, and the - module doesn't fail if the device I(dev) doesn't actually exist. + - When O(state=absent), all other options but O(dev) are ignored, and the + module does not fail if the device O(dev) doesn't actually exist. type: str choices: [ present, absent ] default: present @@ -43,7 +43,7 @@ options: choices: [ btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs ] description: - Filesystem type to be created. This option is required with - I(state=present) (or if I(state) is omitted). + O(state=present) (or if O(state) is omitted). - ufs support has been added in community.general 3.4.0. type: str aliases: [type] @@ -53,20 +53,20 @@ options: regular file (both). - When setting Linux-specific filesystem types on FreeBSD, this module only works when applying to regular files, aka disk images. - - Currently C(lvm) (Linux-only) and C(ufs) (FreeBSD-only) don't support - a regular file as their target I(dev). + - Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support + a regular file as their target O(dev). - Support for character devices on FreeBSD has been added in community.general 3.4.0. type: path required: true aliases: [device] force: description: - - If C(true), allows to create new filesystem on devices that already has filesystem. + - If V(true), allows to create new filesystem on devices that already has filesystem. type: bool default: false resizefs: description: - - If C(true), if the block device and filesystem size differ, grow the filesystem into the space. + - If V(true), if the block device and filesystem size differ, grow the filesystem into the space. - Supported for C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) filesystems. Attempts to resize other filesystem types will fail. - XFS Will only grow if mounted. Currently, the module is based on commands @@ -80,20 +80,20 @@ options: - List of options to be passed to C(mkfs) command. type: str requirements: - - Uses specific tools related to the I(fstype) for creating or resizing a + - Uses specific tools related to the O(fstype) for creating or resizing a filesystem (from packages e2fsprogs, xfsprogs, dosfstools, and so on). - Uses generic tools mostly related to the Operating System (Linux or FreeBSD) or available on both, as C(blkid). - On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required. notes: - - Potential filesystems on I(dev) are checked using C(blkid). In case C(blkid) + - Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) is unable to detect a filesystem (and in case C(fstyp) on FreeBSD is also unable to detect a filesystem), this filesystem is overwritten even if - I(force) is C(false). + O(force) is V(false). - On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide a C(blkid) command that is compatible with this module. However, these packages conflict with each other, and only the C(util-linux) package - provides the command required to not fail when I(state=absent). + provides the command required to not fail when O(state=absent). seealso: - module: community.general.filesize - module: ansible.posix.mount diff --git a/plugins/modules/flatpak.py b/plugins/modules/flatpak.py index 40a13736f0..80dbabdfa0 100644 --- a/plugins/modules/flatpak.py +++ b/plugins/modules/flatpak.py @@ -39,8 +39,8 @@ options: method: description: - The installation method to use. - - Defines if the I(flatpak) is supposed to be installed globally for the whole C(system) - or only for the current C(user). + - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) + or only for the current V(user). type: str choices: [ system, user ] default: system @@ -48,14 +48,14 @@ options: description: - The name of the flatpak to manage. To operate on several packages this can accept a list of packages. - - When used with I(state=present), I(name) can be specified as a URL to a + - When used with O(state=present), O(name) can be specified as a URL to a C(flatpakref) file or the unique reverse DNS name that identifies a flatpak. - Both C(https://) and C(http://) URLs are supported. - - When supplying a reverse DNS name, you can use the I(remote) option to specify on what remote + - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit). - - When used with I(state=absent), it is recommended to specify the name in the reverse DNS + - When used with O(state=absent), it is recommended to specify the name in the reverse DNS format. - - When supplying a URL with I(state=absent), the module will try to match the + - When supplying a URL with O(state=absent), the module will try to match the installed flatpak based on the name of the flatpakref to remove it. However, there is no guarantee that the names of the flatpakref file and the reverse DNS name of the installed flatpak do match. @@ -74,7 +74,7 @@ options: remote: description: - The flatpak remote (repository) to install the flatpak from. - - By default, C(flathub) is assumed, but you do need to add the flathub flatpak_remote before + - By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before you can use this. - See the M(community.general.flatpak_remote) module for managing flatpak remotes. type: str diff --git a/plugins/modules/flatpak_remote.py b/plugins/modules/flatpak_remote.py index 9c097c411f..a4eb3ea27c 100644 --- a/plugins/modules/flatpak_remote.py +++ b/plugins/modules/flatpak_remote.py @@ -18,7 +18,7 @@ description: - Allows users to add or remove flatpak remotes. - The flatpak remotes concept is comparable to what is called repositories in other packaging formats. - - Currently, remote addition is only supported via I(flatpakrepo) file URLs. + - Currently, remote addition is only supported via C(flatpakrepo) file URLs. - Existing remotes will not be updated. - See the M(community.general.flatpak) module for managing flatpaks. author: @@ -42,26 +42,26 @@ options: default: flatpak flatpakrepo_url: description: - - The URL to the I(flatpakrepo) file representing the repository remote to add. - - When used with I(state=present), the flatpak remote specified under the I(flatpakrepo_url) - is added using the specified installation C(method). - - When used with I(state=absent), this is not required. - - Required when I(state=present). + - The URL to the C(flatpakrepo) file representing the repository remote to add. + - When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) + is added using the specified installation O(method). + - When used with O(state=absent), this is not required. + - Required when O(state=present). type: str method: description: - The installation method to use. - - Defines if the I(flatpak) is supposed to be installed globally for the whole C(system) - or only for the current C(user). + - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) + or only for the current V(user). type: str choices: [ system, user ] default: system name: description: - The desired name for the flatpak remote to be registered under on the managed host. - - When used with I(state=present), the remote will be added to the managed host under - the specified I(name). - - When used with I(state=absent) the remote with that name will be removed. + - When used with O(state=present), the remote will be added to the managed host under + the specified O(name). + - When used with O(state=absent) the remote with that name will be removed. type: str required: true state: diff --git a/plugins/modules/gandi_livedns.py b/plugins/modules/gandi_livedns.py index cc9dd630b4..fdb7993a5e 100644 --- a/plugins/modules/gandi_livedns.py +++ b/plugins/modules/gandi_livedns.py @@ -44,7 +44,7 @@ options: ttl: description: - The TTL to give the new record. - - Required when I(state=present). + - Required when O(state=present). type: int type: description: @@ -54,7 +54,7 @@ options: values: description: - The record values. - - Required when I(state=present). + - Required when O(state=present). type: list elements: str domain: diff --git a/plugins/modules/gconftool2.py b/plugins/modules/gconftool2.py index 704bfb18d9..3dd46c3695 100644 --- a/plugins/modules/gconftool2.py +++ b/plugins/modules/gconftool2.py @@ -36,18 +36,18 @@ options: description: - Preference keys typically have simple values such as strings, integers, or lists of strings and integers. - This is ignored unless I(state=present). See man gconftool-2(1). + This is ignored unless O(state=present). See man gconftool-2(1). value_type: type: str description: - The type of value being set. - This is ignored unless I(state=present). See man gconftool-2(1). + This is ignored unless O(state=present). See man gconftool-2(1). choices: [ bool, float, int, string ] state: type: str description: - The action to take upon the key/value. - - State C(get) is deprecated and will be removed in community.general 8.0.0. Please use the module M(community.general.gconftool2_info) instead. + - State V(get) is deprecated and will be removed in community.general 8.0.0. Please use the module M(community.general.gconftool2_info) instead. required: true choices: [ absent, get, present ] config_source: @@ -57,8 +57,8 @@ options: See man gconftool-2(1). direct: description: - - Access the config database directly, bypassing server. If I(direct) is - specified then the I(config_source) must be specified as well. + - Access the config database directly, bypassing server. If O(direct) is + specified then the O(config_source) must be specified as well. See man gconftool-2(1). type: bool default: false @@ -85,15 +85,15 @@ RETURN = ''' sample: string value: description: - - The value of the preference key after executing the module or C(null) if key is removed. - - From community.general 7.0.0 onwards it returns C(null) for a non-existent I(key), and returns C("") before that. + - The value of the preference key after executing the module or V(null) if key is removed. + - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that. returned: success type: str sample: "Serif 12" previous_value: description: - The value of the preference key before executing the module. - - From community.general 7.0.0 onwards it returns C(null) for a non-existent I(key), and returns C("") before that. + - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that. returned: success type: str sample: "Serif 12" diff --git a/plugins/modules/git_config.py b/plugins/modules/git_config.py index d673121748..2c6a679f3f 100644 --- a/plugins/modules/git_config.py +++ b/plugins/modules/git_config.py @@ -20,7 +20,7 @@ author: requirements: ['git'] short_description: Read and write git configuration description: - - The C(git_config) module changes git configuration by invoking 'git config'. + - The M(community.general.git_config) module changes git configuration by invoking 'git config'. This is needed if you do not want to use M(ansible.builtin.template) for the entire git config file (for example because you need to change just C(user.email) in /etc/.git/config). Solutions involving M(ansible.builtin.command) are cumbersome or @@ -35,7 +35,7 @@ attributes: options: list_all: description: - - List all settings (optionally limited to a given I(scope)). + - List all settings (optionally limited to a given O(scope)). type: bool default: false name: @@ -50,23 +50,23 @@ options: type: path file: description: - - Path to an adhoc git configuration file to be managed using the C(file) scope. + - Path to an adhoc git configuration file to be managed using the V(file) scope. type: path version_added: 2.0.0 scope: description: - Specify which scope to read/set values from. - This is required when setting config values. - - If this is set to C(local), you must also specify the C(repo) parameter. - - If this is set to C(file), you must also specify the C(file) parameter. - - It defaults to system only when not using I(list_all)=C(true). + - If this is set to V(local), you must also specify the O(repo) parameter. + - If this is set to V(file), you must also specify the O(file) parameter. + - It defaults to system only when not using O(list_all=true). choices: [ "file", "local", "global", "system" ] type: str state: description: - "Indicates the setting should be set/unset. - This parameter has higher precedence than I(value) parameter: - when I(state)=absent and I(value) is defined, I(value) is discarded." + This parameter has higher precedence than O(value) parameter: + when O(state=absent) and O(value) is defined, O(value) is discarded." choices: [ 'present', 'absent' ] default: 'present' type: str @@ -152,13 +152,13 @@ EXAMPLES = ''' RETURN = ''' --- config_value: - description: When I(list_all=false) and value is not set, a string containing the value of the setting in name + description: When O(list_all=false) and value is not set, a string containing the value of the setting in name returned: success type: str sample: "vim" config_values: - description: When I(list_all=true), a dict containing key/value pairs of multiple configuration settings + description: When O(list_all=true), a dict containing key/value pairs of multiple configuration settings returned: success type: dict sample: diff --git a/plugins/modules/github_deploy_key.py b/plugins/modules/github_deploy_key.py index 322650bf70..b65f635801 100644 --- a/plugins/modules/github_deploy_key.py +++ b/plugins/modules/github_deploy_key.py @@ -58,7 +58,7 @@ options: type: str read_only: description: - - If C(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write. + - If V(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write. type: bool default: true state: @@ -69,7 +69,7 @@ options: type: str force: description: - - If C(true), forcefully adds the deploy key by deleting any existing deploy key with the same public key or title. + - If V(true), forcefully adds the deploy key by deleting any existing deploy key with the same public key or title. type: bool default: false username: @@ -78,15 +78,15 @@ options: type: str password: description: - - The password to authenticate with. Alternatively, a personal access token can be used instead of I(username) and I(password) combination. + - The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(password) combination. type: str token: description: - - The OAuth2 token or personal access token to authenticate with. Mutually exclusive with I(password). + - The OAuth2 token or personal access token to authenticate with. Mutually exclusive with O(password). type: str otp: description: - - The 6 digit One Time Password for 2-Factor Authentication. Required together with I(username) and I(password). + - The 6 digit One Time Password for 2-Factor Authentication. Required together with O(username) and O(password). type: int notes: - "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/." diff --git a/plugins/modules/github_key.py b/plugins/modules/github_key.py index 683a963a7f..17523eb89f 100644 --- a/plugins/modules/github_key.py +++ b/plugins/modules/github_key.py @@ -34,7 +34,7 @@ options: type: str pubkey: description: - - SSH public key value. Required when I(state=present). + - SSH public key value. Required when O(state=present). type: str state: description: @@ -44,9 +44,9 @@ options: type: str force: description: - - The default is C(true), which will replace the existing remote key - if it's different than C(pubkey). If C(false), the key will only be - set if no key with the given I(name) exists. + - The default is V(true), which will replace the existing remote key + if it is different than O(pubkey). If V(false), the key will only be + set if no key with the given O(name) exists. type: bool default: true diff --git a/plugins/modules/github_repo.py b/plugins/modules/github_repo.py index 97076c58af..f02ad30ac3 100644 --- a/plugins/modules/github_repo.py +++ b/plugins/modules/github_repo.py @@ -15,7 +15,7 @@ short_description: Manage your repositories on Github version_added: 2.2.0 description: - Manages Github repositories using PyGithub library. - - Authentication can be done with I(access_token) or with I(username) and I(password). + - Authentication can be done with O(access_token) or with O(username) and O(password). extends_documentation_fragment: - community.general.attributes attributes: @@ -27,19 +27,19 @@ options: username: description: - Username used for authentication. - - This is only needed when not using I(access_token). + - This is only needed when not using O(access_token). type: str required: false password: description: - Password used for authentication. - - This is only needed when not using I(access_token). + - This is only needed when not using O(access_token). type: str required: false access_token: description: - Token parameter for authentication. - - This is only needed when not using I(username) and I(password). + - This is only needed when not using O(username) and O(password). type: str required: false name: @@ -50,17 +50,17 @@ options: description: description: - Description for the repository. - - Defaults to empty if I(force_defaults=true), which is the default in this module. - - Defaults to empty if I(force_defaults=false) when creating a new repository. - - This is only used when I(state) is C(present). + - Defaults to empty if O(force_defaults=true), which is the default in this module. + - Defaults to empty if O(force_defaults=false) when creating a new repository. + - This is only used when O(state) is V(present). type: str required: false private: description: - Whether the repository should be private or not. - - Defaults to C(false) if I(force_defaults=true), which is the default in this module. - - Defaults to C(false) if I(force_defaults=false) when creating a new repository. - - This is only used when I(state) is C(present). + - Defaults to V(false) if O(force_defaults=true), which is the default in this module. + - Defaults to V(false) if O(force_defaults=false) when creating a new repository. + - This is only used when O(state=present). type: bool required: false state: @@ -73,7 +73,7 @@ options: organization: description: - Organization for the repository. - - When I(state) is C(present), the repository will be created in the current user profile. + - When O(state=present), the repository will be created in the current user profile. type: str required: false api_url: @@ -84,8 +84,8 @@ options: version_added: "3.5.0" force_defaults: description: - - Overwrite current I(description) and I(private) attributes with defaults if set to C(true), which currently is the default. - - The default for this option will be deprecated in a future version of this collection, and eventually change to C(false). + - Overwrite current O(description) and O(private) attributes with defaults if set to V(true), which currently is the default. + - The default for this option will be deprecated in a future version of this collection, and eventually change to V(false). type: bool default: true required: false @@ -125,7 +125,7 @@ EXAMPLES = ''' RETURN = ''' repo: description: Repository information as JSON. See U(https://docs.github.com/en/rest/reference/repos#get-a-repository). - returned: success and I(state) is C(present) + returned: success and O(state=present) type: dict ''' diff --git a/plugins/modules/gitlab_branch.py b/plugins/modules/gitlab_branch.py index d7eecb33fb..c83f21af32 100644 --- a/plugins/modules/gitlab_branch.py +++ b/plugins/modules/gitlab_branch.py @@ -49,7 +49,7 @@ options: ref_branch: description: - Reference branch to create from. - - This must be specified if I(state=present). + - This must be specified if O(state=present). type: str ''' diff --git a/plugins/modules/gitlab_group_members.py b/plugins/modules/gitlab_group_members.py index 66298e882c..8f8b23e0c0 100644 --- a/plugins/modules/gitlab_group_members.py +++ b/plugins/modules/gitlab_group_members.py @@ -40,22 +40,22 @@ options: gitlab_user: description: - A username or a list of usernames to add to/remove from the GitLab group. - - Mutually exclusive with I(gitlab_users_access). + - Mutually exclusive with O(gitlab_users_access). type: list elements: str access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. - - Mutually exclusive with I(gitlab_users_access). + - Required if O(state=present), user state is set to present. + - Mutually exclusive with O(gitlab_users_access). type: str choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] gitlab_users_access: description: - Provide a list of user to access level mappings. - Every dictionary in this list specifies a user (by username) and the access level the user should have. - - Mutually exclusive with I(gitlab_user) and I(access_level). - - Use together with I(purge_users) to remove all users not specified here from the group. + - Mutually exclusive with O(gitlab_user) and O(access_level). + - Use together with O(purge_users) to remove all users not specified here from the group. type: list elements: dict suboptions: @@ -66,7 +66,7 @@ options: access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. + - Required if O(state=present), user state is set to present. type: str choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] required: true @@ -74,16 +74,16 @@ options: state: description: - State of the member in the group. - - On C(present), it adds a user to a GitLab group. - - On C(absent), it removes a user from a GitLab group. + - On V(present), it adds a user to a GitLab group. + - On V(absent), it removes a user from a GitLab group. choices: ['present', 'absent'] default: 'present' type: str purge_users: description: - - Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list. + - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted do not purge orphaned members. - - Is only used when I(state=present). + - Is only used when O(state=present). type: list elements: str choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] diff --git a/plugins/modules/gitlab_group_variable.py b/plugins/modules/gitlab_group_variable.py index 1a3a0c3c2a..2bba2768f4 100644 --- a/plugins/modules/gitlab_group_variable.py +++ b/plugins/modules/gitlab_group_variable.py @@ -17,7 +17,7 @@ description: - Creates a group variable if it does not exist. - When a group variable does exist, its value will be updated when the values are different. - Variables which are untouched in the playbook, but are not untouched in the GitLab group, - they stay untouched (I(purge) is C(false)) or will be deleted (I(purge) is C(true)). + they stay untouched (O(purge=false)) or will be deleted (O(purge=true)). author: - Florent Madiot (@scodeman) requirements: @@ -48,20 +48,20 @@ options: type: str purge: description: - - When set to C(true), delete all variables which are not untouched in the task. + - When set to V(true), delete all variables which are not untouched in the task. default: false type: bool vars: description: - When the list element is a simple key-value pair, set masked and protected to false. - - When the list element is a dict with the keys I(value), I(masked) and I(protected), the user can + - When the list element is a dict with the keys C(value), C(masked) and C(protected), the user can have full control about whether a value should be masked, protected or both. - Support for group variables requires GitLab >= 9.5. - Support for environment_scope requires GitLab Premium >= 13.11. - Support for protected values requires GitLab >= 9.3. - Support for masked values requires GitLab >= 11.10. - - A I(value) must be a string or a number. - - Field I(variable_type) must be a string with either C(env_var), which is the default, or C(file). + - A C(value) must be a string or a number. + - Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file). - When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)). default: {} @@ -70,7 +70,7 @@ options: version_added: 4.5.0 description: - A list of dictionaries that represents CI/CD variables. - - This modules works internal with this sructure, even if the older I(vars) parameter is used. + - This modules works internal with this sructure, even if the older O(vars) parameter is used. default: [] type: list elements: dict @@ -83,7 +83,7 @@ options: value: description: - The variable value. - - Required when I(state=present). + - Required when O(state=present). type: str masked: description: @@ -97,7 +97,7 @@ options: default: false variable_type: description: - - Wether a variable is an environment variable (C(env_var)) or a file (C(file)). + - Wether a variable is an environment variable (V(env_var)) or a file (V(file)). type: str choices: [ "env_var", "file" ] default: env_var diff --git a/plugins/modules/gitlab_instance_variable.py b/plugins/modules/gitlab_instance_variable.py index 9b5db36883..0217a1484d 100644 --- a/plugins/modules/gitlab_instance_variable.py +++ b/plugins/modules/gitlab_instance_variable.py @@ -19,7 +19,7 @@ description: - When a instance variable does exist, its value will be updated if the values are different. - Support for instance variables requires GitLab >= 13.0. - Variables which are not mentioned in the modules options, but are present on the GitLab instance, - will either stay (I(purge=false)) or will be deleted (I(purge=true)). + will either stay (O(purge=false)) or will be deleted (O(purge=true)). author: - Benedikt Braunger (@benibr) requirements: @@ -45,7 +45,7 @@ options: choices: ["present", "absent"] purge: description: - - When set to C(true), delete all variables which are not mentioned in the task. + - When set to V(true), delete all variables which are not mentioned in the task. default: false type: bool variables: @@ -63,7 +63,7 @@ options: value: description: - The variable value. - - Required when I(state=present). + - Required when O(state=present). type: str masked: description: @@ -77,7 +77,7 @@ options: default: false variable_type: description: - - Wether a variable is an environment variable (C(env_var)) or a file (C(file)). + - Wether a variable is an environment variable (V(env_var)) or a file (V(file)). type: str choices: [ "env_var", "file" ] default: env_var diff --git a/plugins/modules/gitlab_project.py b/plugins/modules/gitlab_project.py index db360d5789..b10a062577 100644 --- a/plugins/modules/gitlab_project.py +++ b/plugins/modules/gitlab_project.py @@ -15,7 +15,7 @@ module: gitlab_project short_description: Creates/updates/deletes GitLab Projects description: - When the project does not exist in GitLab, it will be created. - - When the project does exists and I(state=absent), the project will be deleted. + - When the project does exists and O(state=absent), the project will be deleted. - When changes are made to the project, the project will be updated. author: - Werner Dijkerman (@dj-wasabi) @@ -84,9 +84,9 @@ options: default: true visibility: description: - - C(private) Project access must be granted explicitly for each user. - - C(internal) The project can be cloned by any logged in user. - - C(public) The project can be cloned without any authentication. + - V(private) Project access must be granted explicitly for each user. + - V(internal) The project can be cloned by any logged in user. + - V(public) The project can be cloned without any authentication. default: private type: str choices: ["private", "internal", "public"] @@ -108,7 +108,7 @@ options: merge_method: description: - What requirements are placed upon merges. - - Possible values are C(merge), C(rebase_merge) merge commit with semi-linear history, C(ff) fast-forward merges only. + - Possible values are V(merge), V(rebase_merge) merge commit with semi-linear history, V(ff) fast-forward merges only. type: str choices: ["ff", "merge", "rebase_merge"] default: merge @@ -176,78 +176,78 @@ options: default_branch: description: - Default branch name for a new project. - - This option is only used on creation, not for updates. This is also only used if I(initialize_with_readme=true). + - This option is only used on creation, not for updates. This is also only used if O(initialize_with_readme=true). type: str version_added: "4.2.0" builds_access_level: description: - - C(private) means that repository CI/CD is allowed only to project members. - - C(disabled) means that repository CI/CD is disabled. - - C(enabled) means that repository CI/CD is enabled. + - V(private) means that repository CI/CD is allowed only to project members. + - V(disabled) means that repository CI/CD is disabled. + - V(enabled) means that repository CI/CD is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.2.0" forking_access_level: description: - - C(private) means that repository forks is allowed only to project members. - - C(disabled) means that repository forks are disabled. - - C(enabled) means that repository forks are enabled. + - V(private) means that repository forks is allowed only to project members. + - V(disabled) means that repository forks are disabled. + - V(enabled) means that repository forks are enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.2.0" container_registry_access_level: description: - - C(private) means that container registry is allowed only to project members. - - C(disabled) means that container registry is disabled. - - C(enabled) means that container registry is enabled. + - V(private) means that container registry is allowed only to project members. + - V(disabled) means that container registry is disabled. + - V(enabled) means that container registry is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.2.0" releases_access_level: description: - - C(private) means that accessing release is allowed only to project members. - - C(disabled) means that accessing release is disabled. - - C(enabled) means that accessing release is enabled. + - V(private) means that accessing release is allowed only to project members. + - V(disabled) means that accessing release is disabled. + - V(enabled) means that accessing release is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" environments_access_level: description: - - C(private) means that deployment to environment is allowed only to project members. - - C(disabled) means that deployment to environment is disabled. - - C(enabled) means that deployment to environment is enabled. + - V(private) means that deployment to environment is allowed only to project members. + - V(disabled) means that deployment to environment is disabled. + - V(enabled) means that deployment to environment is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" feature_flags_access_level: description: - - C(private) means that feature rollout is allowed only to project members. - - C(disabled) means that feature rollout is disabled. - - C(enabled) means that feature rollout is enabled. + - V(private) means that feature rollout is allowed only to project members. + - V(disabled) means that feature rollout is disabled. + - V(enabled) means that feature rollout is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" infrastructure_access_level: description: - - C(private) means that configuring infrastructure is allowed only to project members. - - C(disabled) means that configuring infrastructure is disabled. - - C(enabled) means that configuring infrastructure is enabled. + - V(private) means that configuring infrastructure is allowed only to project members. + - V(disabled) means that configuring infrastructure is disabled. + - V(enabled) means that configuring infrastructure is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" monitor_access_level: description: - - C(private) means that monitoring health is allowed only to project members. - - C(disabled) means that monitoring health is disabled. - - C(enabled) means that monitoring health is enabled. + - V(private) means that monitoring health is allowed only to project members. + - V(disabled) means that monitoring health is disabled. + - V(enabled) means that monitoring health is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" security_and_compliance_access_level: description: - - C(private) means that accessing security and complicance tab is allowed only to project members. - - C(disabled) means that accessing security and complicance tab is disabled. - - C(enabled) means that accessing security and complicance tab is enabled. + - V(private) means that accessing security and complicance tab is allowed only to project members. + - V(disabled) means that accessing security and complicance tab is disabled. + - V(enabled) means that accessing security and complicance tab is enabled. type: str choices: ["private", "disabled", "enabled"] version_added: "6.4.0" diff --git a/plugins/modules/gitlab_project_badge.py b/plugins/modules/gitlab_project_badge.py index 5b1a8d3f1c..917534a9b8 100644 --- a/plugins/modules/gitlab_project_badge.py +++ b/plugins/modules/gitlab_project_badge.py @@ -39,8 +39,8 @@ options: state: description: - State of the badge in the project. - - On C(present), it adds a badge to a GitLab project. - - On C(absent), it removes a badge from a GitLab project. + - On V(present), it adds a badge to a GitLab project. + - On V(absent), it removes a badge from a GitLab project. choices: ['present', 'absent'] default: 'present' type: str @@ -82,7 +82,7 @@ EXAMPLES = r''' RETURN = ''' badge: description: The badge information. - returned: when I(state=present) + returned: when O(state=present) type: dict sample: id: 1 diff --git a/plugins/modules/gitlab_project_members.py b/plugins/modules/gitlab_project_members.py index 9053584431..177bec072d 100644 --- a/plugins/modules/gitlab_project_members.py +++ b/plugins/modules/gitlab_project_members.py @@ -42,21 +42,21 @@ options: gitlab_user: description: - A username or a list of usernames to add to/remove from the GitLab project. - - Mutually exclusive with I(gitlab_users_access). + - Mutually exclusive with O(gitlab_users_access). type: list elements: str access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. + - Required if O(state=present), user state is set to present. type: str choices: ['guest', 'reporter', 'developer', 'maintainer'] gitlab_users_access: description: - Provide a list of user to access level mappings. - Every dictionary in this list specifies a user (by username) and the access level the user should have. - - Mutually exclusive with I(gitlab_user) and I(access_level). - - Use together with I(purge_users) to remove all users not specified here from the project. + - Mutually exclusive with O(gitlab_user) and O(access_level). + - Use together with O(purge_users) to remove all users not specified here from the project. type: list elements: dict suboptions: @@ -67,7 +67,7 @@ options: access_level: description: - The access level for the user. - - Required if I(state=present), user state is set to present. + - Required if O(state=present), user state is set to present. type: str choices: ['guest', 'reporter', 'developer', 'maintainer'] required: true @@ -75,16 +75,16 @@ options: state: description: - State of the member in the project. - - On C(present), it adds a user to a GitLab project. - - On C(absent), it removes a user from a GitLab project. + - On V(present), it adds a user to a GitLab project. + - On V(absent), it removes a user from a GitLab project. choices: ['present', 'absent'] default: 'present' type: str purge_users: description: - - Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list. + - Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted do not purge orphaned members. - - Is only used when I(state=present). + - Is only used when O(state=present). type: list elements: str choices: ['guest', 'reporter', 'developer', 'maintainer'] diff --git a/plugins/modules/gitlab_project_variable.py b/plugins/modules/gitlab_project_variable.py index 7287358a32..6423754e1d 100644 --- a/plugins/modules/gitlab_project_variable.py +++ b/plugins/modules/gitlab_project_variable.py @@ -14,7 +14,7 @@ description: - When a project variable does not exist, it will be created. - When a project variable does exist, its value will be updated when the values are different. - Variables which are untouched in the playbook, but are not untouched in the GitLab project, - they stay untouched (I(purge) is C(false)) or will be deleted (I(purge) is C(true)). + they stay untouched (O(purge=false)) or will be deleted (O(purge=true)). author: - "Markus Bergholz (@markuman)" requirements: @@ -52,15 +52,15 @@ options: vars: description: - When the list element is a simple key-value pair, masked and protected will be set to false. - - When the list element is a dict with the keys I(value), I(masked) and I(protected), the user can + - When the list element is a dict with the keys C(value), C(masked) and C(protected), the user can have full control about whether a value should be masked, protected or both. - Support for protected values requires GitLab >= 9.3. - Support for masked values requires GitLab >= 11.10. - Support for environment_scope requires GitLab Premium >= 13.11. - Support for variable_type requires GitLab >= 11.11. - - A I(value) must be a string or a number. - - Field I(variable_type) must be a string with either C(env_var), which is the default, or C(file). - - Field I(environment_scope) must be a string defined by scope environment. + - A C(value) must be a string or a number. + - Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file). + - Field C(environment_scope) must be a string defined by scope environment. - When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables). default: {} @@ -69,7 +69,7 @@ options: version_added: 4.4.0 description: - A list of dictionaries that represents CI/CD variables. - - This module works internal with this structure, even if the older I(vars) parameter is used. + - This module works internal with this structure, even if the older O(vars) parameter is used. default: [] type: list elements: dict @@ -82,7 +82,7 @@ options: value: description: - The variable value. - - Required when I(state=present). + - Required when O(state=present). type: str masked: description: @@ -98,15 +98,15 @@ options: default: false variable_type: description: - - Wether a variable is an environment variable (C(env_var)) or a file (C(file)). - - Support for I(variable_type) requires GitLab >= 11.11. + - Wether a variable is an environment variable (V(env_var)) or a file (V(file)). + - Support for O(variables[].variable_type) requires GitLab >= 11.11. type: str choices: ["env_var", "file"] default: env_var environment_scope: description: - The scope for the variable. - - Support for I(environment_scope) requires GitLab Premium >= 13.11. + - Support for O(variables[].environment_scope) requires GitLab Premium >= 13.11. type: str default: '*' ''' diff --git a/plugins/modules/gitlab_runner.py b/plugins/modules/gitlab_runner.py index 50f3b3f524..2bfb3bf3d7 100644 --- a/plugins/modules/gitlab_runner.py +++ b/plugins/modules/gitlab_runner.py @@ -24,7 +24,7 @@ description: To create shared runners, you need to ask your administrator to give you this token. It can be found at U(https://$GITLAB_URL/admin/runners/). notes: - - To create a new runner at least the C(api_token), C(description) and C(api_url) options are required. + - To create a new runner at least the O(api_token), O(description) and O(api_url) options are required. - Runners need to have unique descriptions. author: - Samy Coenen (@SamyCoenen) @@ -47,14 +47,14 @@ options: group: description: - ID or full path of the group in the form group/subgroup. - - Mutually exclusive with I(owned) and I(project). + - Mutually exclusive with O(owned) and O(project). type: str version_added: '6.5.0' project: description: - ID or full path of the project in the form of group/name. - - Mutually exclusive with I(owned) since community.general 4.5.0. - - Mutually exclusive with I(group). + - Mutually exclusive with O(owned) since community.general 4.5.0. + - Mutually exclusive with O(group). type: str version_added: '3.7.0' description: @@ -74,13 +74,13 @@ options: registration_token: description: - The registration token is used to register new runners. - - Required if I(state) is C(present). + - Required if O(state=present). type: str owned: description: - Searches only runners available to the user when searching for existing, when false admin token required. - - Mutually exclusive with I(project) since community.general 4.5.0. - - Mutually exclusive with I(group). + - Mutually exclusive with O(project) since community.general 4.5.0. + - Mutually exclusive with O(group). default: false type: bool version_added: 2.0.0 @@ -99,12 +99,12 @@ options: access_level: description: - Determines if a runner can pick up jobs only from protected branches. - - If I(access_level_on_creation) is not explicitly set to C(true), this option is ignored on registration and + - If O(access_level_on_creation) is not explicitly set to V(true), this option is ignored on registration and is only applied on updates. - - If set to C(not_protected), runner can pick up jobs from both protected and unprotected branches. - - If set to C(ref_protected), runner can pick up jobs only from protected branches. - - The current default is C(ref_protected). This will change to no default in community.general 8.0.0. - From that version on, if this option is not specified explicitly, GitLab will use C(not_protected) + - If set to V(not_protected), runner can pick up jobs from both protected and unprotected branches. + - If set to V(ref_protected), runner can pick up jobs only from protected branches. + - The current default is V(ref_protected). This will change to no default in community.general 8.0.0. + From that version on, if this option is not specified explicitly, GitLab will use V(not_protected) on creation, and the value set will not be changed on any updates. required: false choices: ["not_protected", "ref_protected"] @@ -112,9 +112,9 @@ options: access_level_on_creation: description: - Whether the runner should be registered with an access level or not. - - If set to C(true), the value of I(access_level) is used for runner registration. - - If set to C(false), GitLab registers the runner with the default access level. - - The default of this option changed to C(true) in community.general 7.0.0. Before, it was C(false). + - If set to V(true), the value of O(access_level) is used for runner registration. + - If set to V(false), GitLab registers the runner with the default access level. + - The default of this option changed to V(true) in community.general 7.0.0. Before, it was V(false). required: false default: true type: bool diff --git a/plugins/modules/gitlab_user.py b/plugins/modules/gitlab_user.py index 94f3713160..21211cdf35 100644 --- a/plugins/modules/gitlab_user.py +++ b/plugins/modules/gitlab_user.py @@ -45,7 +45,7 @@ options: name: description: - Name of the user you want to create. - - Required only if C(state) is set to C(present). + - Required only if O(state=present). type: str username: description: @@ -66,7 +66,7 @@ options: email: description: - The email that belongs to the user. - - Required only if C(state) is set to C(present). + - Required only if O(state=present). type: str sshkey_name: description: @@ -123,7 +123,7 @@ options: identities: description: - List of identities to be added/updated for this user. - - To remove all other identities from this user, set I(overwrite_identities=true). + - To remove all other identities from this user, set O(overwrite_identities=true). type: list elements: dict suboptions: @@ -139,8 +139,8 @@ options: overwrite_identities: description: - Overwrite identities with identities added in this module. - - This means that all identities that the user has and that are not listed in I(identities) are removed from the user. - - This is only done if a list is provided for I(identities). To remove all identities, provide an empty list. + - This means that all identities that the user has and that are not listed in O(identities) are removed from the user. + - This is only done if a list is provided for O(identities). To remove all identities, provide an empty list. type: bool default: false version_added: 3.3.0 diff --git a/plugins/modules/grove.py b/plugins/modules/grove.py index b3e0508ffa..d1a5f3126a 100644 --- a/plugins/modules/grove.py +++ b/plugins/modules/grove.py @@ -39,7 +39,7 @@ options: type: str description: - Message content. - - The alias I(message) is deprecated and will be removed in community.general 4.0.0. + - The alias O(ignore:message) has been removed in community.general 4.0.0. required: true url: type: str