From a66b9fc5c98d6ac68a8a57905d42d362849cae66 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 26 Dec 2024 22:44:22 +0100 Subject: [PATCH] [PR #9395/3048d530 backport][stable-9] g*.py: normalize docs (#9414) g*.py: normalize docs (#9395) * g*.py: normalize docs * Update plugins/modules/gandi_livedns.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein (cherry picked from commit 3048d5305d3d3a08d92a5f10b407a9993c6c8799) Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/modules/gandi_livedns.py | 114 +++++++-------- plugins/modules/gconftool2.py | 44 +++--- plugins/modules/gconftool2_info.py | 33 ++--- plugins/modules/gem.py | 32 ++-- plugins/modules/gio_mime.py | 42 +++--- plugins/modules/git_config.py | 63 ++++---- plugins/modules/git_config_info.py | 29 ++-- plugins/modules/github_deploy_key.py | 71 ++++----- plugins/modules/github_issue.py | 26 ++-- plugins/modules/github_key.py | 46 +++--- plugins/modules/github_release.py | 138 +++++++++--------- plugins/modules/github_repo.py | 68 ++++----- plugins/modules/github_webhook.py | 50 +++---- plugins/modules/github_webhook_info.py | 28 ++-- plugins/modules/gitlab_branch.py | 13 +- plugins/modules/gitlab_deploy_key.py | 29 ++-- plugins/modules/gitlab_group.py | 31 ++-- plugins/modules/gitlab_group_access_token.py | 22 +-- plugins/modules/gitlab_group_members.py | 15 +- plugins/modules/gitlab_group_variable.py | 26 ++-- plugins/modules/gitlab_hook.py | 31 ++-- plugins/modules/gitlab_instance_variable.py | 18 +-- plugins/modules/gitlab_issue.py | 18 +-- plugins/modules/gitlab_label.py | 24 +-- plugins/modules/gitlab_merge_request.py | 17 +-- plugins/modules/gitlab_milestone.py | 12 +- plugins/modules/gitlab_project.py | 20 ++- .../modules/gitlab_project_access_token.py | 22 +-- plugins/modules/gitlab_project_badge.py | 13 +- plugins/modules/gitlab_project_members.py | 15 +- plugins/modules/gitlab_project_variable.py | 24 +-- plugins/modules/gitlab_protected_branch.py | 13 +- plugins/modules/gitlab_runner.py | 59 ++++---- plugins/modules/gitlab_user.py | 36 ++--- plugins/modules/grove.py | 22 ++- plugins/modules/gunicorn.py | 52 +++---- 36 files changed, 633 insertions(+), 683 deletions(-) diff --git a/plugins/modules/gandi_livedns.py b/plugins/modules/gandi_livedns.py index ad2e96fd15..e90483a49d 100644 --- a/plugins/modules/gandi_livedns.py +++ b/plugins/modules/gandi_livedns.py @@ -8,15 +8,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: gandi_livedns author: - Gregory Thiemonge (@gthiemonge) version_added: "2.3.0" short_description: Manage Gandi LiveDNS records description: - - "Manages DNS records by the Gandi LiveDNS API, see the docs: U(https://doc.livedns.gandi.net/)." + - 'Manages DNS records by the Gandi LiveDNS API, see the docs: U(https://doc.livedns.gandi.net/).' extends_documentation_fragment: - community.general.attributes attributes: @@ -27,32 +26,31 @@ attributes: options: personal_access_token: description: - - Scoped API token. - - One of O(personal_access_token) and O(api_key) must be specified. + - Scoped API token. + - One of O(personal_access_token) and O(api_key) must be specified. type: str version_added: 9.0.0 api_key: description: - - Account API token. - - Note that these type of keys are deprecated and might stop working at some point. - Use personal access tokens instead. - - One of O(personal_access_token) and O(api_key) must be specified. + - Account API token. + - Note that these type of keys are deprecated and might stop working at some point. Use personal access tokens instead. + - One of O(personal_access_token) and O(api_key) must be specified. type: str record: description: - - Record to add. + - Record to add. type: str required: true state: description: - - Whether the record(s) should exist or not. + - Whether the record(s) should exist or not. type: str - choices: [ absent, present ] + choices: [absent, present] default: present ttl: description: - - The TTL to give the new record. - - Required when O(state=present). + - The TTL to give the new record. + - Required when O(state=present). type: int type: description: @@ -61,25 +59,25 @@ options: required: true values: description: - - The record values. - - Required when O(state=present). + - The record values. + - Required when O(state=present). type: list elements: str domain: description: - - The name of the Domain to work with (for example, "example.com"). + - The name of the Domain to work with (for example, V(example.com)). required: true type: str -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create a test A record to point to 127.0.0.1 in the my.com domain community.general.gandi_livedns: domain: my.com record: test type: A values: - - 127.0.0.1 + - 127.0.0.1 ttl: 7200 personal_access_token: dummytoken register: record @@ -90,7 +88,7 @@ EXAMPLES = r''' type: CNAME record: mail values: - - www + - www ttl: 7200 personal_access_token: dummytoken state: present @@ -101,7 +99,7 @@ EXAMPLES = r''' type: CNAME record: mail values: - - www + - www ttl: 10800 personal_access_token: dummytoken state: present @@ -120,46 +118,46 @@ EXAMPLES = r''' record: test type: A values: - - 127.0.0.1 + - 127.0.0.1 ttl: 7200 api_key: dummyapikey -''' +""" -RETURN = r''' +RETURN = r""" record: - description: A dictionary containing the record data. - returned: success, except on record deletion - type: dict - contains: - values: - description: The record content (details depend on record type). - returned: success - type: list - elements: str - sample: - - 192.0.2.91 - - 192.0.2.92 - record: - description: The record name. - returned: success - type: str - sample: www - ttl: - description: The time-to-live for the record. - returned: success - type: int - sample: 300 - type: - description: The record type. - returned: success - type: str - sample: A - domain: - description: The domain associated with the record. - returned: success - type: str - sample: my.com -''' + description: A dictionary containing the record data. + returned: success, except on record deletion + type: dict + contains: + values: + description: The record content (details depend on record type). + returned: success + type: list + elements: str + sample: + - 192.0.2.91 + - 192.0.2.92 + record: + description: The record name. + returned: success + type: str + sample: www + ttl: + description: The time-to-live for the record. + returned: success + type: int + sample: 300 + type: + description: The record type. + returned: success + type: str + sample: A + domain: + description: The domain associated with the record. + returned: success + type: str + sample: my.com +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gconftool2.py b/plugins/modules/gconftool2.py index 7cf9a92c44..2f66448520 100644 --- a/plugins/modules/gconftool2.py +++ b/plugins/modules/gconftool2.py @@ -9,21 +9,21 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: gconftool2 author: -- Kenneth D. Evensen (@kevensen) + - Kenneth D. Evensen (@kevensen) short_description: Edit GNOME Configurations description: -- This module allows for the manipulation of GNOME 2 Configuration via gconftool-2. Please see the gconftool-2(1) man pages for more details. + - This module allows for the manipulation of GNOME 2 Configuration using C(gconftool-2). Please see the gconftool-2(1) man pages + for more details. seealso: -- name: C(gconftool-2) command manual page - description: Manual page for the command. - link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en + - name: C(gconftool-2) command manual page + description: Manual page for the command. + link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en extends_documentation_fragment: -- community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -33,36 +33,37 @@ options: key: type: str description: - - A GConf preference key is an element in the GConf repository that corresponds to an application preference. + - A GConf preference key is an element in the GConf repository that corresponds to an application preference. required: true value: type: str description: - - Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is ignored unless O(state=present). + - Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is + ignored unless O(state=present). value_type: type: str description: - - The type of value being set. This is ignored unless O(state=present). + - The type of value being set. This is ignored unless O(state=present). choices: [bool, float, int, string] state: type: str description: - - The action to take upon the key/value. + - The action to take upon the key/value. required: true choices: [absent, present] config_source: type: str description: - - Specify a configuration source to use rather than the default path. + - Specify a configuration source to use rather than the default path. direct: description: - - Access the config database directly, bypassing server. If O(direct) is specified then the O(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. type: bool default: false """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Change the widget font to "Serif 12" community.general.gconftool2: key: "/desktop/gnome/interface/font_name" @@ -70,8 +71,7 @@ EXAMPLES = """ value: "Serif 12" """ -RETURN = """ ---- +RETURN = r""" key: description: The key specified in the module parameters. returned: success @@ -84,15 +84,15 @@ value_type: sample: string value: description: - - 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. + - 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 V(null) for a non-existent O(key), and returned V("") before that. + - The value of the preference key before executing the module. + - 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/gconftool2_info.py b/plugins/modules/gconftool2_info.py index ebe2121ad1..3c1baf9a65 100644 --- a/plugins/modules/gconftool2_info.py +++ b/plugins/modules/gconftool2_info.py @@ -7,46 +7,43 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: gconftool2_info author: -- "Alexei Znamensky (@russoz)" + - "Alexei Znamensky (@russoz)" short_description: Retrieve GConf configurations version_added: 5.1.0 description: -- This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2). + - This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2). extends_documentation_fragment: -- community.general.attributes -- community.general.attributes.info_module + - community.general.attributes + - community.general.attributes.info_module options: key: description: - - The key name for an element in the GConf database. + - The key name for an element in the GConf database. type: str required: true seealso: -- name: C(gconftool-2) command manual page - description: Manual page for the command. - link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en -- name: gconf repository (archived) - description: Git repository for the project. It is an archived project, so the repository is read-only. - link: https://gitlab.gnome.org/Archive/gconf + - name: C(gconftool-2) command manual page + description: Manual page for the command. + link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en + - name: gconf repository (archived) + description: Git repository for the project. It is an archived project, so the repository is read-only. + link: https://gitlab.gnome.org/Archive/gconf """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Get value for a certain key in the database. community.general.gconftool2_info: key: /desktop/gnome/background/picture_filename register: result """ -RETURN = """ ---- +RETURN = r""" value: description: - - The value of the property. + - The value of the property. returned: success type: str sample: Monospace 10 diff --git a/plugins/modules/gem.py b/plugins/modules/gem.py index f51e3350da..c01433cb90 100644 --- a/plugins/modules/gem.py +++ b/plugins/modules/gem.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: gem short_description: Manage Ruby gems description: @@ -49,38 +48,37 @@ options: repository: type: str description: - - The repository from which the gem will be installed + - The repository from which the gem will be installed. required: false aliases: [source] user_install: description: - - Install gem in user's local gems cache or for all users + - Install gem in user's local gems cache or for all users. required: false type: bool default: true executable: type: path description: - - Override the path to the gem executable + - Override the path to the gem executable. required: false install_dir: type: path description: - - Install the gems into a specific directory. - These gems will be independent from the global installed ones. - Specifying this requires user_install to be false. + - Install the gems into a specific directory. These gems will be independent from the global installed ones. Specifying + this requires user_install to be false. required: false bindir: type: path description: - - Install executables into a specific directory. + - Install executables into a specific directory. version_added: 3.3.0 norc: type: bool default: true description: - - Avoid loading any C(.gemrc) file. Ignored for RubyGems prior to 2.5.2. - - The default changed from V(false) to V(true) in community.general 6.0.0. + - Avoid loading any C(.gemrc) file. Ignored for RubyGems prior to 2.5.2. + - The default changed from V(false) to V(true) in community.general 6.0.0. version_added: 3.3.0 env_shebang: description: @@ -108,7 +106,7 @@ options: build_flags: type: str description: - - Allow adding build flags for gem compilation + - Allow adding build flags for gem compilation. required: false force: description: @@ -117,11 +115,11 @@ options: default: false type: bool author: - - "Ansible Core Team" - - "Johan Wiren (@johanwiren)" -''' + - "Ansible Core Team" + - "Johan Wiren (@johanwiren)" +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install version 1.0 of vagrant community.general.gem: name: vagrant @@ -138,7 +136,7 @@ EXAMPLES = ''' name: rake gem_source: /path/to/gems/rake-1.0.gem state: present -''' +""" import re diff --git a/plugins/modules/gio_mime.py b/plugins/modules/gio_mime.py index 20ccb22329..8ac4b34838 100644 --- a/plugins/modules/gio_mime.py +++ b/plugins/modules/gio_mime.py @@ -7,17 +7,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: gio_mime author: -- "Alexei Znamensky (@russoz)" + - "Alexei Znamensky (@russoz)" short_description: Set default handler for MIME type, for applications using Gnome GIO version_added: 7.5.0 description: -- This module allows configuring the default handler for a specific MIME type, to be used by applications built with th Gnome GIO API. + - This module allows configuring the default handler for a specific MIME type, to be used by applications built with the + Gnome GIO API. extends_documentation_fragment: -- community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -26,28 +26,27 @@ attributes: options: mime_type: description: - - MIME type for which a default handler will be set. + - MIME type for which a default handler will be set. type: str required: true handler: description: - - Default handler will be set for the MIME type. + - Default handler will be set for the MIME type. type: str required: true notes: -- This module is a thin wrapper around the C(gio mime) command (and subcommand). -- See man gio(1) for more details. + - This module is a thin wrapper around the C(gio mime) command (and subcommand). + - See man gio(1) for more details. seealso: -- name: C(gio) command manual page - description: Manual page for the command. - link: https://man.archlinux.org/man/gio.1 -- name: GIO Documentation - description: Reference documentation for the GIO API.. - link: https://docs.gtk.org/gio/ + - name: C(gio) command manual page + description: Manual page for the command. + link: https://man.archlinux.org/man/gio.1 + - name: GIO Documentation + description: Reference documentation for the GIO API.. + link: https://docs.gtk.org/gio/ """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Set chrome as the default handler for https community.general.gio_mime: mime_type: x-scheme-handler/https @@ -55,23 +54,22 @@ EXAMPLES = """ register: result """ -RETURN = """ ---- +RETURN = r""" handler: description: - - The handler set as default. + - The handler set as default. returned: success type: str sample: google-chrome.desktop stdout: description: - - The output of the C(gio) command. + - The output of the C(gio) command. returned: success type: str sample: Set google-chrome.desktop as the default for x-scheme-handler/https stderr: description: - - The error output of the C(gio) command. + - The error output of the C(gio) command. returned: failure type: str sample: 'gio: Failed to load info for handler "never-existed.desktop"' diff --git a/plugins/modules/git_config.py b/plugins/modules/git_config.py index 95969c1b38..6a6eff0be2 100644 --- a/plugins/modules/git_config.py +++ b/plugins/modules/git_config.py @@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: git_config author: - Matthew Gamble (@djmattyg007) @@ -20,11 +19,10 @@ author: requirements: ['git'] short_description: Update git configuration description: - - The M(community.general.git_config) module changes git configuration by invoking C(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 - do not work correctly in check mode. + - The M(community.general.git_config) module changes git configuration by invoking C(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 C(/etc/.git/config)). Solutions involving M(ansible.builtin.command) are cumbersome or do not work + correctly in check mode. extends_documentation_fragment: - community.general.attributes attributes: @@ -36,19 +34,17 @@ options: list_all: description: - List all settings (optionally limited to a given O(scope)). - - This option is B(deprecated) and will be removed from community.general 11.0.0. - Please use M(community.general.git_config_info) instead. + - This option is B(deprecated) and will be removed from community.general 11.0.0. Please use M(community.general.git_config_info) + instead. type: bool default: false name: description: - - The name of the setting. If no value is supplied, the value will - be read from the config if it has been set. + - The name of the setting. If no value is supplied, the value will be read from the config if it has been set. type: str repo: description: - - Path to a git repository for reading and writing values from a - specific repo. + - Path to a git repository for reading and writing values from a specific repo. type: path file: description: @@ -62,36 +58,34 @@ options: - 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" ] + choices: ["file", "local", "global", "system"] type: str state: description: - - "Indicates the setting should be set/unset. - 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' ] + - 'Indicates the setting should be set/unset. 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 value: description: - - When specifying the name of a single setting, supply a value to - set that setting to the given value. - - From community.general 11.0.0 on, O(value) will be required if O(state=present). - To read values, use the M(community.general.git_config_info) module instead. + - When specifying the name of a single setting, supply a value to set that setting to the given value. + - From community.general 11.0.0 on, O(value) will be required if O(state=present). To read values, use the M(community.general.git_config_info) + module instead. type: str add_mode: description: - - Specify if a value should replace the existing value(s) or if the new - value should be added alongside other values with the same name. - - This option is only relevant when adding/replacing values. If O(state=absent) or - values are just read out, this option is not considered. - choices: [ "add", "replace-all" ] + - Specify if a value should replace the existing value(s) or if the new value should be added alongside other values + with the same name. + - This option is only relevant when adding/replacing values. If O(state=absent) or values are just read out, this option + is not considered. + choices: ["add", "replace-all"] type: str default: "replace-all" version_added: 8.1.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Add a setting to ~/.gitconfig community.general.git_config: name: alias.ci @@ -147,18 +141,17 @@ EXAMPLES = ''' repo: /etc scope: local value: 'root@{{ ansible_fqdn }}' -''' +""" -RETURN = ''' ---- +RETURN = r""" config_value: - description: When O(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 O(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: @@ -166,7 +159,7 @@ config_values: color.ui: "auto" alias.diffc: "diff --cached" alias.remotev: "remote -v" -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/git_config_info.py b/plugins/modules/git_config_info.py index 147201fff3..c8152cfa42 100644 --- a/plugins/modules/git_config_info.py +++ b/plugins/modules/git_config_info.py @@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: git_config_info author: - Guenther Grill (@guenhter) @@ -19,8 +18,7 @@ version_added: 8.1.0 requirements: ['git'] short_description: Read git configuration description: - - The M(community.general.git_config_info) module reads the git configuration - by invoking C(git config). + - The M(community.general.git_config_info) module reads the git configuration by invoking C(git config). extends_documentation_fragment: - community.general.attributes - community.general.attributes.info_module @@ -44,12 +42,12 @@ options: - If set to V(system), the system git config is used. O(path) is ignored. - If set to V(local), O(path) must be set to the repo to read from. - If set to V(file), O(path) must be set to the config file to read from. - choices: [ "global", "system", "local", "file" ] + choices: ["global", "system", "local", "file"] default: "system" type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Read a system wide config community.general.git_config_info: name: core.editor @@ -81,14 +79,13 @@ EXAMPLES = ''' community.general.git_config_info: scope: file path: /etc/gitconfig -''' +""" -RETURN = ''' ---- +RETURN = r""" config_value: - description: > - When O(name) is set, a string containing the value of the setting in name. If O(name) is not set, empty. - If a config key such as V(push.pushoption) has more then one entry, just the first one is returned here. + description: >- + When O(name) is set, a string containing the value of the setting in name. If O(name) is not set, empty. If a config key + such as V(push.pushoption) has more then one entry, just the first one is returned here. returned: success if O(name) is set type: str sample: "vim" @@ -97,8 +94,8 @@ config_values: description: - This is a dictionary mapping a git configuration setting to a list of its values. - When O(name) is not set, all configuration settings are returned here. - - When O(name) is set, only the setting specified in O(name) is returned here. - If that setting is not set, the key will still be present, and its value will be an empty list. + - When O(name) is set, only the setting specified in O(name) is returned here. If that setting is not set, the key will + still be present, and its value will be an empty list. returned: success type: dict sample: @@ -106,7 +103,7 @@ config_values: color.ui: ["auto"] push.pushoption: ["merge_request.create", "merge_request.draft"] alias.remotev: ["remote -v"] -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/github_deploy_key.py b/plugins/modules/github_deploy_key.py index ae90e04c91..509a67c491 100644 --- a/plugins/modules/github_deploy_key.py +++ b/plugins/modules/github_deploy_key.py @@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: github_deploy_key author: "Ali (@bincyber)" short_description: Manages deploy keys for GitHub repositories description: - - "Adds or removes deploy keys for GitHub repositories. Supports authentication using username and password, - username and password and 2-factor authentication code (OTP), OAuth2 token, or personal access token. Admin - rights on the repository are required." + - Adds or removes deploy keys for GitHub repositories. Supports authentication using username and password, username and + password and 2-factor authentication code (OTP), OAuth2 token, or personal access token. Admin rights on the repository + are required. extends_documentation_fragment: - community.general.attributes attributes: @@ -28,7 +27,7 @@ attributes: options: github_url: description: - - The base URL of the GitHub API + - The base URL of the GitHub API. required: false type: str version_added: '0.2.0' @@ -37,19 +36,19 @@ options: description: - The name of the individual account or organization that owns the GitHub repository. required: true - aliases: [ 'account', 'organization' ] + aliases: ['account', 'organization'] type: str repo: description: - The name of the GitHub repository. required: true - aliases: [ 'repository' ] + aliases: ['repository'] type: str name: description: - The name for the deploy key. required: true - aliases: [ 'title', 'label' ] + aliases: ['title', 'label'] type: str key: description: @@ -58,14 +57,15 @@ options: type: str read_only: description: - - 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. + - 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: description: - The state of the deploy key. default: "present" - choices: [ "present", "absent" ] + choices: ["present", "absent"] type: str force: description: @@ -74,11 +74,12 @@ options: default: false username: description: - - The username to authenticate with. Should not be set when using personal access token + - The username to authenticate with. Should not be set when using personal access token. type: str password: description: - - The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(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: @@ -89,10 +90,10 @@ options: - 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/." -''' + - "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/." +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Add a new read-only deploy key to a GitHub repository using basic authentication community.general.github_deploy_key: owner: "johndoe" @@ -152,33 +153,33 @@ EXAMPLES = ''' read_only: true username: "janedoe" password: "supersecretpassword" -''' +""" -RETURN = ''' +RETURN = r""" msg: - description: the status message describing what occurred - returned: always - type: str - sample: "Deploy key added successfully" + description: The status message describing what occurred. + returned: always + type: str + sample: "Deploy key added successfully" http_status_code: - description: the HTTP status code returned by the GitHub API - returned: failed - type: int - sample: 400 + description: The HTTP status code returned by the GitHub API. + returned: failed + type: int + sample: 400 error: - description: the error message returned by the GitHub API - returned: failed - type: str - sample: "key is already in use" + description: The error message returned by the GitHub API. + returned: failed + type: str + sample: "key is already in use" id: - description: the key identifier assigned by GitHub for the deploy key - returned: changed - type: int - sample: 24381901 -''' + description: The key identifier assigned by GitHub for the deploy key. + returned: changed + type: int + sample: 24381901 +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.urls import fetch_url diff --git a/plugins/modules/github_issue.py b/plugins/modules/github_issue.py index 4e10e9f925..86e81d38ef 100644 --- a/plugins/modules/github_issue.py +++ b/plugins/modules/github_issue.py @@ -10,7 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: github_issue short_description: View GitHub issue description: @@ -40,24 +40,24 @@ options: type: int action: description: - - Get various details about issue depending upon action specified. + - Get various details about issue depending upon action specified. default: 'get_status' choices: - - 'get_status' + - get_status type: str author: - - Abhijeet Kasurde (@Akasurde) -''' + - Abhijeet Kasurde (@Akasurde) +""" -RETURN = ''' +RETURN = r""" issue_status: - description: State of the GitHub issue - type: str - returned: success - sample: open, closed -''' + description: State of the GitHub issue. + type: str + returned: success + sample: open, closed +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Check if GitHub issue is closed or not community.general.github_issue: organization: ansible @@ -70,7 +70,7 @@ EXAMPLES = ''' ansible.builtin.debug: msg: Do something when issue 23642 is open when: r.issue_status == 'open' -''' +""" import json diff --git a/plugins/modules/github_key.py b/plugins/modules/github_key.py index b071e7b339..f3d5863d54 100644 --- a/plugins/modules/github_key.py +++ b/plugins/modules/github_key.py @@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: github_key short_description: Manage GitHub access keys description: @@ -29,7 +29,7 @@ options: type: str name: description: - - SSH key name + - SSH key name. required: true type: str pubkey: @@ -44,34 +44,36 @@ options: type: str force: description: - - 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. + - 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 author: Robert Estelle (@erydo) -''' +""" -RETURN = ''' +RETURN = r""" deleted_keys: - description: An array of key objects that were deleted. Only present on state=absent - type: list - returned: When state=absent - sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}] + description: An array of key objects that were deleted. Only present on state=absent. + type: list + returned: When state=absent + sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', + 'read_only': false}] matching_keys: - description: An array of keys matching the specified name. Only present on state=present - type: list - returned: When state=present - sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}] + description: An array of keys matching the specified name. Only present on state=present. + type: list + returned: When state=present + sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', + 'read_only': false}] key: - description: Metadata about the key just created. Only present on state=present - type: dict - returned: success - sample: {'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false} -''' + description: Metadata about the key just created. Only present on state=present. + type: dict + returned: success + sample: {'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', + 'read_only': false} +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Read SSH public key to authorize ansible.builtin.shell: cat /home/foo/.ssh/id_rsa.pub register: ssh_pub_key @@ -89,7 +91,7 @@ EXAMPLES = ''' name: Access Key for Some Machine token: '{{ github_access_token }}' pubkey: "{{ lookup('ansible.builtin.file', '/home/foo/.ssh/id_rsa.pub') }}" -''' +""" import datetime import json diff --git a/plugins/modules/github_release.py b/plugins/modules/github_release.py index d8ee155b81..1376bf4f3d 100644 --- a/plugins/modules/github_release.py +++ b/plugins/modules/github_release.py @@ -9,78 +9,77 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: github_release short_description: Interact with GitHub Releases description: - - Fetch metadata about GitHub Releases + - Fetch metadata about GitHub Releases. extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: full - diff_mode: - support: none + check_mode: + support: full + diff_mode: + support: none options: - token: - description: - - GitHub Personal Access Token for authenticating. Mutually exclusive with O(password). - type: str - user: - description: - - The GitHub account that owns the repository - type: str - required: true - password: - description: - - The GitHub account password for the user. Mutually exclusive with O(token). - type: str - repo: - description: - - Repository name - type: str - required: true - action: - description: - - Action to perform - type: str - required: true - choices: [ 'latest_release', 'create_release' ] - tag: - description: - - Tag name when creating a release. Required when using O(action=create_release). - type: str - target: - description: - - Target of release when creating a release - type: str - name: - description: - - Name of release when creating a release - type: str - body: - description: - - Description of the release when creating a release - type: str - draft: - description: - - Sets if the release is a draft or not. (boolean) - type: bool - default: false - prerelease: - description: - - Sets if the release is a prerelease or not. (boolean) - type: bool - default: false + token: + description: + - GitHub Personal Access Token for authenticating. Mutually exclusive with O(password). + type: str + user: + description: + - The GitHub account that owns the repository. + type: str + required: true + password: + description: + - The GitHub account password for the user. Mutually exclusive with O(token). + type: str + repo: + description: + - Repository name. + type: str + required: true + action: + description: + - Action to perform. + type: str + required: true + choices: ['latest_release', 'create_release'] + tag: + description: + - Tag name when creating a release. Required when using O(action=create_release). + type: str + target: + description: + - Target of release when creating a release. + type: str + name: + description: + - Name of release when creating a release. + type: str + body: + description: + - Description of the release when creating a release. + type: str + draft: + description: + - Sets if the release is a draft or not. (boolean). + type: bool + default: false + prerelease: + description: + - Sets if the release is a prerelease or not. (boolean). + type: bool + default: false author: - - "Adrian Moisey (@adrianmoisey)" + - "Adrian Moisey (@adrianmoisey)" requirements: - - "github3.py >= 1.0.0a3" -''' + - "github3.py >= 1.0.0a3" +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Get latest release of a public repository community.general.github_release: user: ansible @@ -111,16 +110,15 @@ EXAMPLES = ''' target: master name: My Release body: Some description +""" -''' - -RETURN = ''' +RETURN = r""" tag: - description: Version of the created/latest release. - type: str - returned: success - sample: 1.1.0 -''' + description: Version of the created/latest release. + type: str + returned: success + sample: 1.1.0 +""" import traceback diff --git a/plugins/modules/github_repo.py b/plugins/modules/github_repo.py index f02ad30ac3..2d2c6f8588 100644 --- a/plugins/modules/github_repo.py +++ b/plugins/modules/github_repo.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: github_repo short_description: Manage your repositories on Github version_added: 2.2.0 @@ -26,81 +25,82 @@ attributes: options: username: description: - - Username used for authentication. - - This is only needed when not using O(access_token). + - Username used for authentication. + - 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 O(access_token). + - Password used for authentication. + - 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 O(username) and O(password). + - Token parameter for authentication. + - This is only needed when not using O(username) and O(password). type: str required: false name: description: - - Repository name. + - Repository name. type: str required: true description: description: - - Description for the repository. - - 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). + - Description for the repository. + - 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 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). + - Whether the repository should be private or not. + - 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: description: - - Whether the repository should exist or not. + - Whether the repository should exist or not. type: str default: present - choices: [ absent, present ] + choices: [absent, present] required: false organization: description: - - Organization for the repository. - - When O(state=present), the repository will be created in the current user profile. + - Organization for the repository. + - When O(state=present), the repository will be created in the current user profile. type: str required: false api_url: description: - - URL to the GitHub API if not using github.com but you own instance. + - URL to the GitHub API if not using github.com but you own instance. type: str default: 'https://api.github.com' version_added: "3.5.0" force_defaults: description: - - 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). + - 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 version_added: 4.1.0 requirements: -- PyGithub>=1.54 + - PyGithub>=1.54 notes: -- For Python 3, PyGithub>=1.54 should be used. -- "For Python 3.5, PyGithub==1.54 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-54-november-30-2020)." -- "For Python 2.7, PyGithub==1.45 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-45-december-29-2019)." + - For Python 3, PyGithub>=1.54 should be used. + - 'For Python 3.5, PyGithub==1.54 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-54-november-30-2020).' + - 'For Python 2.7, PyGithub==1.45 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-45-december-29-2019).' author: -- Álvaro Torres Cogollo (@atorrescogollo) -''' + - Álvaro Torres Cogollo (@atorrescogollo) +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a Github repository community.general.github_repo: access_token: mytoken @@ -120,14 +120,14 @@ EXAMPLES = ''' name: myrepo state: absent register: result -''' +""" -RETURN = ''' +RETURN = r""" repo: description: Repository information as JSON. See U(https://docs.github.com/en/rest/reference/repos#get-a-repository). returned: success and O(state=present) type: dict -''' +""" import traceback from ansible.module_utils.basic import AnsibleModule, missing_required_lib diff --git a/plugins/modules/github_webhook.py b/plugins/modules/github_webhook.py index 11b115750b..8608c90bc9 100644 --- a/plugins/modules/github_webhook.py +++ b/plugins/modules/github_webhook.py @@ -8,12 +8,11 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: github_webhook short_description: Manage GitHub webhooks description: - - "Create and delete GitHub webhooks" + - Create and delete GitHub webhooks. requirements: - "PyGithub >= 1.3.5" extends_documentation_fragment: @@ -26,22 +25,22 @@ attributes: options: repository: description: - - Full name of the repository to configure a hook for + - Full name of the repository to configure a hook for. type: str required: true aliases: - repo url: description: - - URL to which payloads will be delivered + - URL to which payloads will be delivered. type: str required: true content_type: description: - - The media type used to serialize the payloads + - The media type used to serialize the payloads. type: str required: false - choices: [ form, json ] + choices: [form, json] default: form secret: description: @@ -50,61 +49,57 @@ options: required: false insecure_ssl: description: - - > - Flag to indicate that GitHub should skip SSL verification when calling - the hook. + - Flag to indicate that GitHub should skip SSL verification when calling the hook. required: false type: bool default: false events: description: - - > - A list of GitHub events the hook is triggered for. Events are listed at - U(https://developer.github.com/v3/activity/events/types/). Required - unless O(state=absent) + - A list of GitHub events the hook is triggered for. Events are listed at U(https://developer.github.com/v3/activity/events/types/). + Required unless O(state=absent). required: false type: list elements: str active: description: - - Whether or not the hook is active + - Whether or not the hook is active. required: false type: bool default: true state: description: - - Whether the hook should be present or absent + - Whether the hook should be present or absent. type: str required: false - choices: [ absent, present ] + choices: [absent, present] default: present user: description: - - User to authenticate to GitHub as + - User to authenticate to GitHub as. type: str required: true password: description: - - Password to authenticate to GitHub with + - Password to authenticate to GitHub with. type: str required: false token: description: - - Token to authenticate to GitHub with + - Token to authenticate to GitHub with. type: str required: false github_url: description: - - Base URL of the GitHub API + - Base URL of the GitHub API. type: str required: false default: https://api.github.com author: - "Chris St. Pierre (@stpierre)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a new webhook that triggers on push (password auth) community.general.github_webhook: repository: ansible/ansible @@ -135,16 +130,15 @@ EXAMPLES = ''' state: absent user: "{{ github_user }}" password: "{{ github_password }}" -''' +""" -RETURN = ''' ---- +RETURN = r""" hook_id: - description: The GitHub ID of the hook created/updated + description: The GitHub ID of the hook created/updated. returned: when state is 'present' type: int sample: 6206 -''' +""" import traceback diff --git a/plugins/modules/github_webhook_info.py b/plugins/modules/github_webhook_info.py index dcad02a369..440a373f1d 100644 --- a/plugins/modules/github_webhook_info.py +++ b/plugins/modules/github_webhook_info.py @@ -8,12 +8,11 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: github_webhook_info short_description: Query information about GitHub webhooks description: - - "Query information about GitHub webhooks" + - Query information about GitHub webhooks. requirements: - "PyGithub >= 1.3.5" extends_documentation_fragment: @@ -22,38 +21,38 @@ extends_documentation_fragment: options: repository: description: - - Full name of the repository to configure a hook for + - Full name of the repository to configure a hook for. type: str required: true aliases: - repo user: description: - - User to authenticate to GitHub as + - User to authenticate to GitHub as. type: str required: true password: description: - - Password to authenticate to GitHub with + - Password to authenticate to GitHub with. type: str required: false token: description: - - Token to authenticate to GitHub with + - Token to authenticate to GitHub with. type: str required: false github_url: description: - - Base URL of the github api + - Base URL of the GitHub API. type: str required: false default: https://api.github.com author: - "Chris St. Pierre (@stpierre)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: List hooks for a repository (password auth) community.general.github_webhook_info: repository: ansible/ansible @@ -68,12 +67,11 @@ EXAMPLES = ''' token: "{{ github_user_api_token }}" github_url: https://github.example.com/api/v3/ register: myrepo_webhooks -''' +""" -RETURN = ''' ---- +RETURN = r""" hooks: - description: A list of hooks that exist for the repo + description: A list of hooks that exist for the repo. returned: always type: list elements: dict @@ -88,7 +86,7 @@ hooks: "id": 6206, "last_response": {"status": "active", "message": "OK", "code": 200} } -''' +""" import traceback diff --git a/plugins/modules/gitlab_branch.py b/plugins/modules/gitlab_branch.py index 623c25644e..b32169ef5a 100644 --- a/plugins/modules/gitlab_branch.py +++ b/plugins/modules/gitlab_branch.py @@ -7,7 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_branch short_description: Create or delete a branch version_added: 4.2.0 @@ -50,10 +50,10 @@ options: - Reference branch to create from. - This must be specified if O(state=present). type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create branch branch2 from main community.general.gitlab_branch: api_url: https://gitlab.com @@ -70,11 +70,10 @@ EXAMPLES = ''' project: "group1/project1" branch: branch2 state: absent +""" -''' - -RETURN = ''' -''' +RETURN = r""" +""" import traceback diff --git a/plugins/modules/gitlab_deploy_key.py b/plugins/modules/gitlab_deploy_key.py index ab89520248..5a2f582357 100644 --- a/plugins/modules/gitlab_deploy_key.py +++ b/plugins/modules/gitlab_deploy_key.py @@ -11,11 +11,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_deploy_key short_description: Manages GitLab project deploy keys description: - - Adds, updates and removes project deploy keys + - Adds, updates and removes project deploy keys. author: - Marcus Watkins (@marwatk) - Guillaume Martinez (@Lunik) @@ -45,7 +45,7 @@ options: type: str key: description: - - Deploy key + - Deploy key. required: true type: str can_push: @@ -55,14 +55,14 @@ options: default: false state: description: - - When V(present) the deploy key added to the project if it doesn't exist. + - When V(present) the deploy key added to the project if it does not exist. - When V(absent) it will be removed from the project if it exists. default: present type: str - choices: [ "present", "absent" ] -''' + choices: ["present", "absent"] +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: "Adding a project deploy key" community.general.gitlab_deploy_key: api_url: https://gitlab.example.com/ @@ -88,32 +88,31 @@ EXAMPLES = ''' project: "my_group/my_project" state: absent key: "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9w..." +""" -''' - -RETURN = ''' +RETURN = r""" msg: - description: Success or failure message + description: Success or failure message. returned: always type: str sample: "Success" result: - description: json parsed response from the server + description: JSON-parsed response from the server. returned: always type: dict error: - description: the error message returned by the GitLab API + description: The error message returned by the GitLab API. returned: failed type: str sample: "400: key is already in use" deploy_key: - description: API object + description: API object. returned: always type: dict -''' +""" from ansible.module_utils.api import basic_auth_argument_spec from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gitlab_group.py b/plugins/modules/gitlab_group.py index f8db33360c..711318c6d4 100644 --- a/plugins/modules/gitlab_group.py +++ b/plugins/modules/gitlab_group.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: gitlab_group short_description: Creates/updates/deletes GitLab Groups description: @@ -97,12 +96,12 @@ options: type: str parent: description: - - Allow to create subgroups - - Id or Full path of parent group in the form of group/name + - Allow to create subgroups. + - Id or Full path of parent group in the form of group/name. type: str path: description: - - The path of the group you want to create, this will be api_url/group_path + - The path of the group you want to create, this will be api_url/group_path. - If not supplied, the group_name will be used. type: str prevent_forking_outside_group: @@ -146,7 +145,7 @@ options: version_added: 3.7.0 state: description: - - create or delete group. + - Create or delete group. - Possible values are present and absent. default: present type: str @@ -164,7 +163,7 @@ options: version_added: 9.5.0 visibility: description: - - Default visibility of the group + - Default visibility of the group. choices: ["private", "internal", "public"] default: private type: str @@ -176,9 +175,9 @@ options: choices: ["enabled", "private", "disabled"] type: str version_added: 9.5.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: "Delete GitLab Group" community.general.gitlab_group: api_url: https://gitlab.example.com/ @@ -221,31 +220,31 @@ EXAMPLES = ''' project_creation_level: noone auto_devops_enabled: false subgroup_creation_level: maintainer -''' +""" -RETURN = ''' +RETURN = r""" msg: - description: Success or failure message + description: Success or failure message. returned: always type: str sample: "Success" result: - description: json parsed response from the server + description: JSON-parsed response from the server. returned: always type: dict error: - description: the error message returned by the GitLab API + description: The error message returned by the GitLab API. returned: failed type: str sample: "400: path is already in use" group: - description: API object + description: API object. returned: always type: dict -''' +""" from ansible.module_utils.api import basic_auth_argument_spec from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gitlab_group_access_token.py b/plugins/modules/gitlab_group_access_token.py index 1db7414081..bcf75e056b 100644 --- a/plugins/modules/gitlab_group_access_token.py +++ b/plugins/modules/gitlab_group_access_token.py @@ -12,7 +12,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: gitlab_group_access_token short_description: Manages GitLab group access tokens version_added: 8.4.0 @@ -27,11 +27,10 @@ extends_documentation_fragment: - community.general.gitlab - community.general.attributes notes: - - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. - Whether tokens will be recreated is controlled by the O(recreate) option, which defaults to V(never). + - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. Whether tokens + will be recreated is controlled by the O(recreate) option, which defaults to V(never). - Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards. - Token matching is done by comparing O(name) option. - attributes: check_mode: support: full @@ -56,7 +55,8 @@ options: type: list elements: str aliases: ["scope"] - choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", "ai_features", "k8s_proxy"] + choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", + "ai_features", "k8s_proxy"] access_level: description: - Access level of the access token. @@ -84,10 +84,10 @@ options: - When V(absent) it will be removed from the group if it exists. default: present type: str - choices: [ "present", "absent" ] -''' + choices: ["present", "absent"] +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: "Creating a group access token" community.general.gitlab_group_access_token: api_url: https://gitlab.example.com/ @@ -131,16 +131,16 @@ EXAMPLES = r''' - write_repository recreate: state_change state: present -''' +""" -RETURN = r''' +RETURN = r""" access_token: description: - API object. - Only contains the value of the token if the token was created or recreated. returned: success and O(state=present) type: dict -''' +""" from datetime import datetime diff --git a/plugins/modules/gitlab_group_members.py b/plugins/modules/gitlab_group_members.py index ca82891e30..86e9e6474a 100644 --- a/plugins/modules/gitlab_group_members.py +++ b/plugins/modules/gitlab_group_members.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: gitlab_group_members short_description: Manage group members on GitLab Server description: @@ -81,16 +80,16 @@ options: type: str purge_users: description: - - 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. + - 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 O(state=present). type: list elements: str choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner'] version_added: 3.6.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Add a user to a GitLab Group community.general.gitlab_group_members: api_url: 'https://gitlab.example.com' @@ -152,9 +151,9 @@ EXAMPLES = r''' - name: user2 access_level: maintainer state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.api import basic_auth_argument_spec from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gitlab_group_variable.py b/plugins/modules/gitlab_group_variable.py index 32e5aaa904..926f4fe20a 100644 --- a/plugins/modules/gitlab_group_variable.py +++ b/plugins/modules/gitlab_group_variable.py @@ -9,15 +9,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: gitlab_group_variable short_description: Creates, updates, or deletes GitLab groups variables version_added: 1.2.0 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 (O(purge=false)) or will be deleted (O(purge=true)). + - Variables which are untouched in the playbook, but are not untouched in the GitLab group, they stay untouched (O(purge=false)) + or will be deleted (O(purge=true)). author: - Florent Madiot (@scodeman) requirements: @@ -53,8 +53,8 @@ options: vars: description: - When the list element is a simple key-value pair, masked, raw and protected will be set to false. - - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can - have full control about whether a value should be masked, raw, protected or both. + - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can have full + control about whether a value should be masked, raw, 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. @@ -62,8 +62,8 @@ options: - Support for raw values requires GitLab >= 15.7. - 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)). + - 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: {} type: dict variables: @@ -106,17 +106,17 @@ options: description: - Whether a variable is an environment variable (V(env_var)) or a file (V(file)). type: str - choices: [ "env_var", "file" ] + choices: ["env_var", "file"] default: env_var environment_scope: description: - The scope for the variable. type: str default: '*' -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Set or update some CI/CD variables community.general.gitlab_group_variable: api_url: https://gitlab.com @@ -173,9 +173,9 @@ EXAMPLES = r''' state: absent vars: ACCESS_KEY_ID: abc123 -''' +""" -RETURN = r''' +RETURN = r""" group_variable: description: Four lists of the variablenames which were added, updated, removed or exist. returned: always @@ -201,7 +201,7 @@ group_variable: returned: always type: list sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY'] -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_hook.py b/plugins/modules/gitlab_hook.py index 58781d182b..ccc3310ce5 100644 --- a/plugins/modules/gitlab_hook.py +++ b/plugins/modules/gitlab_hook.py @@ -11,12 +11,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: gitlab_hook short_description: Manages GitLab project hooks description: - - Adds, updates and removes project hook + - Adds, updates and removes project hook. author: - Marcus Watkins (@marwatk) - Guillaume Martinez (@Lunik) @@ -46,11 +45,11 @@ options: type: str state: description: - - When V(present) the hook will be updated to match the input or created if it doesn't exist. + - When V(present) the hook will be updated to match the input or created if it does not exist. - When V(absent) hook will be deleted if it exists. default: present type: str - choices: [ "present", "absent" ] + choices: ["present", "absent"] push_events: description: - Trigger hook on push events. @@ -58,7 +57,7 @@ options: default: true push_events_branch_filter: description: - - Branch name of wildcard to trigger hook on push events + - Branch name of wildcard to trigger hook on push events. type: str version_added: '0.2.0' default: '' @@ -107,7 +106,7 @@ options: - Whether GitLab will do SSL verification when triggering the hook. type: bool default: false - aliases: [ enable_ssl_verification ] + aliases: [enable_ssl_verification] token: description: - Secret token to validate hook messages at the receiver. @@ -115,9 +114,9 @@ options: - Will show up in the X-GitLab-Token HTTP request header. required: false type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: "Adding a project hook" community.general.gitlab_hook: api_url: https://gitlab.example.com/ @@ -144,31 +143,31 @@ EXAMPLES = ''' project: 10 hook_url: "https://my-ci-server.example.com/gitlab-hook" state: absent -''' +""" -RETURN = ''' +RETURN = r""" msg: - description: Success or failure message + description: Success or failure message. returned: always type: str sample: "Success" result: - description: json parsed response from the server + description: Json parsed response from the server. returned: always type: dict error: - description: the error message returned by the GitLab API + description: The error message returned by the GitLab API. returned: failed type: str sample: "400: path is already in use" hook: - description: API object + description: API object. returned: always type: dict -''' +""" from ansible.module_utils.api import basic_auth_argument_spec from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gitlab_instance_variable.py b/plugins/modules/gitlab_instance_variable.py index cc2d812ca3..be89238eb4 100644 --- a/plugins/modules/gitlab_instance_variable.py +++ b/plugins/modules/gitlab_instance_variable.py @@ -10,7 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: gitlab_instance_variable short_description: Creates, updates, or deletes GitLab instance variables version_added: 7.1.0 @@ -18,8 +18,8 @@ description: - Creates a instance variable if it does not exist. - 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 (O(purge=false)) or will be deleted (O(purge=true)). + - Variables which are not mentioned in the modules options, but are present on the GitLab instance, will either stay (O(purge=false)) + or will be deleted (O(purge=true)). author: - Benedikt Braunger (@benibr) requirements: @@ -78,12 +78,12 @@ options: description: - Whether a variable is an environment variable (V(env_var)) or a file (V(file)). type: str - choices: [ "env_var", "file" ] + choices: ["env_var", "file"] default: env_var -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Set or update some CI/CD variables community.general.gitlab_instance_variable: api_url: https://gitlab.com @@ -105,9 +105,9 @@ EXAMPLES = r''' state: absent variables: - name: ACCESS_KEY_ID -''' +""" -RETURN = r''' +RETURN = r""" instance_variable: description: Four lists of the variablenames which were added, updated, removed or exist. returned: always @@ -133,7 +133,7 @@ instance_variable: returned: always type: list sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY'] -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_issue.py b/plugins/modules/gitlab_issue.py index 1ad7d04822..47b6f072e8 100644 --- a/plugins/modules/gitlab_issue.py +++ b/plugins/modules/gitlab_issue.py @@ -12,7 +12,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_issue short_description: Create, update, or delete GitLab issues version_added: '8.1.0' @@ -97,10 +97,10 @@ options: - A title for the issue. The title is used as a unique identifier to ensure idempotency. type: str required: true -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create Issue community.general.gitlab_issue: api_url: https://gitlab.com @@ -109,10 +109,10 @@ EXAMPLES = ''' title: "Ansible demo Issue" description: "Demo Issue description" labels: - - Ansible - - Demo + - Ansible + - Demo assignee_ids: - - testassignee + - testassignee state_filter: "opened" state: present @@ -124,9 +124,9 @@ EXAMPLES = ''' title: "Ansible demo Issue" state_filter: "opened" state: absent -''' +""" -RETURN = r''' +RETURN = r""" msg: description: Success or failure message. returned: always @@ -137,7 +137,7 @@ issue: description: API object. returned: success type: dict -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_label.py b/plugins/modules/gitlab_label.py index f6e9172eb3..44fbf1ae02 100644 --- a/plugins/modules/gitlab_label.py +++ b/plugins/modules/gitlab_label.py @@ -7,9 +7,9 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_label -short_description: Creates/updates/deletes GitLab Labels belonging to project or group. +short_description: Creates/updates/deletes GitLab Labels belonging to project or group version_added: 8.3.0 description: - When a label does not exist, it will be created. @@ -45,12 +45,12 @@ options: required: false project: description: - - The path and name of the project. Either this or O(group) is required. + - The path and name of the project. Either this or O(group) is required. required: false type: str group: description: - - The path of the group. Either this or O(project) is required. + - The path of the group. Either this or O(project) is required. required: false type: str labels: @@ -76,21 +76,21 @@ options: - Integer value to give priority to the label. type: int required: false - default: null + default: description: description: - Label's description. type: str - default: null + default: new_name: description: - Optional field to change label's name. type: str - default: null -''' + default: +""" -EXAMPLES = ''' +EXAMPLES = r""" # same project's task can be executed for group - name: Create one Label community.general.gitlab_label: @@ -185,9 +185,9 @@ EXAMPLES = ''' labels: - name: label-abc123 - name: label-two -''' +""" -RETURN = ''' +RETURN = r""" labels: description: Four lists of the labels which were added, updated, removed or exist. returned: success @@ -217,7 +217,7 @@ labels_obj: description: API object. returned: success type: dict -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_merge_request.py b/plugins/modules/gitlab_merge_request.py index 8e14f0a181..fd6068980a 100644 --- a/plugins/modules/gitlab_merge_request.py +++ b/plugins/modules/gitlab_merge_request.py @@ -12,7 +12,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_merge_request short_description: Create, update, or delete GitLab merge requests version_added: 7.1.0 @@ -21,8 +21,7 @@ description: - When a single merge request does exist, it will be updated if the provided parameters are different. - When a single merge request does exist and O(state=absent), the merge request will be deleted. - When multiple merge requests are detected, the task fails. - - Existing merge requests are matched based on O(title), O(source_branch), O(target_branch), - and O(state_filter) filters. + - Existing merge requests are matched based on O(title), O(source_branch), O(target_branch), and O(state_filter) filters. author: - zvaraondrej (@zvaraondrej) requirements: @@ -102,10 +101,10 @@ options: - Comma separated list of reviewers usernames omitting V(@) character. - Set to empty string to unassign all reviewers. type: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create Merge Request from branch1 to branch2 community.general.gitlab_merge_request: api_url: https://gitlab.com @@ -117,7 +116,7 @@ EXAMPLES = ''' description: "Demo MR description" labels: "Ansible,Demo" state_filter: "opened" - remove_source_branch: True + remove_source_branch: true state: present - name: Delete Merge Request from branch1 to branch2 @@ -130,9 +129,9 @@ EXAMPLES = ''' title: "Ansible demo MR" state_filter: "opened" state: absent -''' +""" -RETURN = r''' +RETURN = r""" msg: description: Success or failure message. returned: always @@ -143,7 +142,7 @@ mr: description: API object. returned: success type: dict -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_milestone.py b/plugins/modules/gitlab_milestone.py index 4b8b933cc0..99b922c4dd 100644 --- a/plugins/modules/gitlab_milestone.py +++ b/plugins/modules/gitlab_milestone.py @@ -7,7 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_milestone short_description: Creates/updates/deletes GitLab Milestones belonging to project or group version_added: 8.3.0 @@ -83,10 +83,10 @@ options: - Milestone's description. type: str default: null -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" # same project's task can be executed for group - name: Create one milestone community.general.gitlab_milestone: @@ -169,9 +169,9 @@ EXAMPLES = ''' milestones: - title: milestone-abc123 - title: milestone-two -''' +""" -RETURN = ''' +RETURN = r""" milestones: description: Four lists of the milestones which were added, updated, removed or exist. returned: success @@ -201,7 +201,7 @@ milestones_obj: description: API object. returned: success type: dict -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_project.py b/plugins/modules/gitlab_project.py index c5bfb4f21d..942e1d9816 100644 --- a/plugins/modules/gitlab_project.py +++ b/plugins/modules/gitlab_project.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: gitlab_project short_description: Creates/updates/deletes GitLab Projects description: @@ -179,8 +178,7 @@ options: default: true lfs_enabled: description: - - Enable Git large file systems to manages large files such - as audio, video, and graphics files. + - Enable Git large file systems to manages large files such as audio, video, and graphics files. type: bool required: false default: false @@ -331,9 +329,9 @@ options: - If an wiki for this project should be available or not. type: bool default: true -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Create GitLab Project community.general.gitlab_project: api_url: https://gitlab.example.com/ @@ -378,9 +376,9 @@ EXAMPLES = r''' api_password: "{{ initial_root_password }}" name: my_second_project group: "10481470" -''' +""" -RETURN = r''' +RETURN = r""" msg: description: Success or failure message. returned: always @@ -388,12 +386,12 @@ msg: sample: "Success" result: - description: json parsed response from the server. + description: JSON-parsed response from the server. returned: always type: dict error: - description: the error message returned by the GitLab API. + description: The error message returned by the GitLab API. returned: failed type: str sample: "400: path is already in use" @@ -402,7 +400,7 @@ project: description: API object. returned: always type: dict -''' +""" from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_project_access_token.py b/plugins/modules/gitlab_project_access_token.py index 9bfbc51cc7..a93d5531bf 100644 --- a/plugins/modules/gitlab_project_access_token.py +++ b/plugins/modules/gitlab_project_access_token.py @@ -12,7 +12,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' +DOCUMENTATION = r""" module: gitlab_project_access_token short_description: Manages GitLab project access tokens version_added: 8.4.0 @@ -27,11 +27,10 @@ extends_documentation_fragment: - community.general.gitlab - community.general.attributes notes: - - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. - Whether tokens will be recreated is controlled by the O(recreate) option, which defaults to V(never). + - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. Whether tokens + will be recreated is controlled by the O(recreate) option, which defaults to V(never). - Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards. - Token matching is done by comparing O(name) option. - attributes: check_mode: support: full @@ -56,7 +55,8 @@ options: type: list elements: str aliases: ["scope"] - choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", "ai_features", "k8s_proxy"] + choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", + "ai_features", "k8s_proxy"] access_level: description: - Access level of the access token. @@ -84,10 +84,10 @@ options: - When V(absent) it will be removed from the project if it exists. default: present type: str - choices: [ "present", "absent" ] -''' + choices: ["present", "absent"] +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: "Creating a project access token" community.general.gitlab_project_access_token: api_url: https://gitlab.example.com/ @@ -131,16 +131,16 @@ EXAMPLES = r''' - write_repository recreate: state_change state: present -''' +""" -RETURN = r''' +RETURN = r""" access_token: description: - API object. - Only contains the value of the token if the token was created or recreated. returned: success and O(state=present) type: dict -''' +""" from datetime import datetime diff --git a/plugins/modules/gitlab_project_badge.py b/plugins/modules/gitlab_project_badge.py index fee9389492..b62d651c7c 100644 --- a/plugins/modules/gitlab_project_badge.py +++ b/plugins/modules/gitlab_project_badge.py @@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: gitlab_project_badge short_description: Manage project badges on GitLab Server version_added: 6.1.0 @@ -57,9 +56,9 @@ options: - A badge is identified by this URL. required: true type: str -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Add a badge to a GitLab Project community.general.gitlab_project_badge: api_url: 'https://example.gitlab.com' @@ -77,9 +76,9 @@ EXAMPLES = r''' state: absent link_url: 'https://example.gitlab.com/%{project_path}' image_url: 'https://example.gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg' -''' +""" -RETURN = ''' +RETURN = r""" badge: description: The badge information. returned: when O(state=present) @@ -91,7 +90,7 @@ badge: rendered_link_url: 'http://example.com/ci_status.svg?project=example-org/example-project&ref=master' rendered_image_url: 'https://shields.io/my/badge' kind: project -''' +""" from ansible.module_utils.api import basic_auth_argument_spec from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gitlab_project_members.py b/plugins/modules/gitlab_project_members.py index 2ce277f688..228af9a062 100644 --- a/plugins/modules/gitlab_project_members.py +++ b/plugins/modules/gitlab_project_members.py @@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: gitlab_project_members short_description: Manage project members on GitLab Server version_added: 2.2.0 @@ -82,16 +81,16 @@ options: type: str purge_users: description: - - 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. + - 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 O(state=present). type: list elements: str choices: ['guest', 'reporter', 'developer', 'maintainer'] version_added: 3.7.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Add a user to a GitLab Project community.general.gitlab_project_members: api_url: 'https://gitlab.example.com' @@ -154,9 +153,9 @@ EXAMPLES = r''' - name: user2 access_level: maintainer state: absent -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.api import basic_auth_argument_spec from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gitlab_project_variable.py b/plugins/modules/gitlab_project_variable.py index 329e7a414b..5903c9b5c4 100644 --- a/plugins/modules/gitlab_project_variable.py +++ b/plugins/modules/gitlab_project_variable.py @@ -7,14 +7,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_project_variable short_description: Creates/updates/deletes GitLab Projects Variables 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 (O(purge=false)) or will be deleted (O(purge=true)). + - Variables which are untouched in the playbook, but are not untouched in the GitLab project, they stay untouched (O(purge=false)) + or will be deleted (O(purge=true)). author: - "Markus Bergholz (@markuman)" requirements: @@ -51,8 +51,8 @@ options: vars: description: - When the list element is a simple key-value pair, masked, raw and protected will be set to false. - - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can - have full control about whether a value should be masked, raw, protected or both. + - When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can have full + control about whether a value should be masked, raw, protected or both. - Support for protected values requires GitLab >= 9.3. - Support for masked values requires GitLab >= 11.10. - Support for raw values requires GitLab >= 15.7. @@ -61,8 +61,8 @@ options: - 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). + - 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: {} type: dict variables: @@ -116,10 +116,10 @@ options: - Support for O(variables[].environment_scope) requires GitLab Premium >= 13.11. type: str default: '*' -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Set or update some CI/CD variables community.general.gitlab_project_variable: api_url: https://gitlab.com @@ -190,9 +190,9 @@ EXAMPLES = ''' state: absent vars: ACCESS_KEY_ID: abc123 -''' +""" -RETURN = ''' +RETURN = r""" project_variable: description: Four lists of the variablenames which were added, updated, removed or exist. returned: always @@ -218,7 +218,7 @@ project_variable: returned: always type: list sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY'] -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_protected_branch.py b/plugins/modules/gitlab_protected_branch.py index 8d2d75736b..4a3b7177ee 100644 --- a/plugins/modules/gitlab_protected_branch.py +++ b/plugins/modules/gitlab_protected_branch.py @@ -7,7 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: gitlab_protected_branch short_description: Manage protection of existing branches version_added: 3.4.0 @@ -58,10 +58,10 @@ options: default: maintainer type: str choices: ["maintainer", "developer", "nobody"] -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create protected branch on main community.general.gitlab_protected_branch: api_url: https://gitlab.com @@ -70,11 +70,10 @@ EXAMPLES = ''' name: main merge_access_levels: maintainer push_access_level: nobody +""" -''' - -RETURN = ''' -''' +RETURN = r""" +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/gitlab_runner.py b/plugins/modules/gitlab_runner.py index 68e50f05ec..62875c552a 100644 --- a/plugins/modules/gitlab_runner.py +++ b/plugins/modules/gitlab_runner.py @@ -10,33 +10,31 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: gitlab_runner short_description: Create, modify and delete GitLab Runners description: - Register, update and delete runners on GitLab Server side with the GitLab API. - All operations are performed using the GitLab API v4. - - For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html) - and U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user). - - A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web interface at - U(https://$GITLAB_URL/profile/personal_access_tokens). - - A valid registration token is required for registering a new runner. - 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/). - - This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through its API. - Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command + - For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html) and + U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user). + - A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web + interface at U(https://$GITLAB_URL/profile/personal_access_tokens). + - A valid registration token is required for registering a new runner. 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/). + - This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through + its API. Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command. notes: - 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, since this attribute is used as key for idempotency + - Runners need to have unique descriptions, since this attribute is used as key for idempotency. author: - Samy Coenen (@SamyCoenen) - Guillaume Martinez (@Lunik) requirements: - - python-gitlab >= 1.5.0 for legacy runner registration workflow - (runner registration token - U(https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated)) - - python-gitlab >= 4.0.0 for new runner registration workflow - (runner authentication token - U(https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token)) + - python-gitlab >= 1.5.0 for legacy runner registration workflow (runner registration token - + U(https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated)) + - python-gitlab >= 4.0.0 for new runner registration workflow (runner authentication token - + U(https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token)) extends_documentation_fragment: - community.general.auth_basic - community.general.gitlab @@ -73,7 +71,8 @@ options: - name state: description: - - Make sure that the runner with the same name exists with the same configuration or delete the runner with the same name. + - Make sure that the runner with the same name exists with the same configuration or delete the runner with the same + name. required: false default: present choices: ["present", "absent"] @@ -118,12 +117,12 @@ options: access_level: description: - Determines if a runner can pick up jobs only from protected branches. - - 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 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 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. - - Before community.general 8.0.0 the default was V(ref_protected). This was changed to no default in community.general 8.0.0. - If this option is not specified explicitly, GitLab will use V(not_protected) on creation, and the value set + - Before community.general 8.0.0 the default was V(ref_protected). This was changed to no default in community.general + 8.0.0. 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"] @@ -156,9 +155,9 @@ options: default: [] type: list elements: str -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create an instance-level runner community.general.gitlab_runner: api_url: https://gitlab.example.com/ @@ -234,31 +233,31 @@ EXAMPLES = ''' state: present project: mygroup/mysubgroup/myproject register: runner # Register module output to run C(gitlab-runner register) command in another task -''' +""" -RETURN = ''' +RETURN = r""" msg: - description: Success or failure message + description: Success or failure message. returned: always type: str sample: "Success" result: - description: json parsed response from the server + description: JSON-parsed response from the server. returned: always type: dict error: - description: the error message returned by the GitLab API + description: The error message returned by the GitLab API. returned: failed type: str sample: "400: path is already in use" runner: - description: API object + description: API object. returned: always type: dict -''' +""" from ansible.module_utils.api import basic_auth_argument_spec from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/gitlab_user.py b/plugins/modules/gitlab_user.py index 6e5ab4ece0..dd8685312d 100644 --- a/plugins/modules/gitlab_user.py +++ b/plugins/modules/gitlab_user.py @@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: gitlab_user short_description: Creates/updates/deletes/blocks/unblocks GitLab Users description: @@ -88,13 +87,8 @@ options: type: str access_level: description: - - The access level to the group. One of the following can be used. - - guest - - reporter - - developer - - master (alias for maintainer) - - maintainer - - owner + - The access level to the group. + - The value V(master) is an alias for V(maintainer). default: guest type: str choices: ["guest", "reporter", "developer", "master", "maintainer", "owner"] @@ -128,7 +122,7 @@ options: suboptions: provider: description: - - The name of the external identity provider + - The name of the external identity provider. type: str extern_uid: description: @@ -143,9 +137,9 @@ options: type: bool default: false version_added: 3.3.0 -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: "Delete GitLab User" community.general.gitlab_user: api_url: https://gitlab.example.com/ @@ -179,8 +173,8 @@ EXAMPLES = ''' password: mysecretpassword email: me@example.com identities: - - provider: Keycloak - extern_uid: f278f95c-12c7-4d51-996f-758cc2eb11bc + - provider: Keycloak + extern_uid: f278f95c-12c7-4d51-996f-758cc2eb11bc state: present group: super_group/mon_group access_level: owner @@ -198,31 +192,31 @@ EXAMPLES = ''' api_token: "{{ access_token }}" username: myusername state: unblocked -''' +""" -RETURN = ''' +RETURN = r""" msg: - description: Success or failure message + description: Success or failure message. returned: always type: str sample: "Success" result: - description: json parsed response from the server + description: JSON-parsed response from the server. returned: always type: dict error: - description: the error message returned by the GitLab API + description: The error message returned by the GitLab API. returned: failed type: str sample: "400: path is already in use" user: - description: API object + description: API object. returned: always type: dict -''' +""" from ansible.module_utils.api import basic_auth_argument_spec diff --git a/plugins/modules/grove.py b/plugins/modules/grove.py index b50546b4da..abdc303f90 100644 --- a/plugins/modules/grove.py +++ b/plugins/modules/grove.py @@ -9,13 +9,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: grove short_description: Sends a notification to a grove.io channel description: - - The C(grove) module sends a message for a service to a Grove.io - channel. + - The C(grove) module sends a message for a service to a Grove.io channel. extends_documentation_fragment: - community.general.attributes attributes: @@ -32,7 +30,7 @@ options: service: type: str description: - - Name of the service (displayed as the "user" in the message) + - Name of the service (displayed as the "user" in the message). required: false default: ansible message_content: @@ -44,29 +42,29 @@ options: url: type: str description: - - Service URL for the web client + - Service URL for the web client. required: false icon_url: type: str description: - - Icon for the service + - Icon for the service. required: false validate_certs: description: - - If V(false), SSL certificates will not be validated. This should only be used - on personally controlled sites using self-signed certificates. + - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using + self-signed certificates. default: true type: bool author: "Jonas Pfenniger (@zimbatm)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Sends a notification to a grove.io channel community.general.grove: channel_token: 6Ph62VBBJOccmtTPZbubiPzdrhipZXtg service: my-app message: 'deployed {{ target }}' -''' +""" from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.six.moves.urllib.parse import urlencode diff --git a/plugins/modules/gunicorn.py b/plugins/modules/gunicorn.py index 2b2abcf8e6..baf24c53b8 100644 --- a/plugins/modules/gunicorn.py +++ b/plugins/modules/gunicorn.py @@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: gunicorn short_description: Run gunicorn with various settings description: - - Starts gunicorn with the parameters specified. Common settings for gunicorn - configuration are supported. For additional configuration use a config file - See U(https://gunicorn-docs.readthedocs.io/en/latest/settings.html) for more - options. It's recommended to always use the chdir option to avoid problems - with the location of the app. + - Starts gunicorn with the parameters specified. Common settings for gunicorn configuration are supported. For additional + configuration use a config file See U(https://gunicorn-docs.readthedocs.io/en/latest/settings.html) for more options. + It's recommended to always use the chdir option to avoid problems with the location of the app. requirements: [gunicorn] author: - - "Alejandro Gomez (@agmezr)" + - "Alejandro Gomez (@agmezr)" extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -40,37 +37,36 @@ options: type: path aliases: ['virtualenv'] description: - - 'Path to the virtualenv directory.' + - Path to the virtualenv directory. config: type: path description: - - 'Path to the gunicorn configuration file.' + - Path to the gunicorn configuration file. aliases: ['conf'] chdir: type: path description: - - 'Chdir to specified directory before apps loading.' + - Chdir to specified directory before apps loading. pid: type: path description: - - 'A filename to use for the PID file. If not set and not found on the configuration file a tmp - pid file will be created to check a successful run of gunicorn.' + - A filename to use for the PID file. If not set and not found on the configuration file a tmp pid file will be created + to check a successful run of gunicorn. worker: type: str choices: ['sync', 'eventlet', 'gevent', 'tornado ', 'gthread', 'gaiohttp'] description: - - 'The type of workers to use. The default class (sync) should handle most "normal" types of workloads.' + - The type of workers to use. The default class (sync) should handle most "normal" types of workloads. user: type: str description: - - 'Switch worker processes to run as this user.' + - Switch worker processes to run as this user. notes: - - If not specified on config file, a temporary error log will be created on /tmp dir. - Please make sure you have write access in /tmp dir. Not needed but will help you to - identify any problem with configuration. -''' + - If not specified on config file, a temporary error log will be created on /tmp dir. Please make sure you have write access + in /tmp dir. Not needed but will help you to identify any problem with configuration. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Simple gunicorn run example community.general.gunicorn: app: 'wsgi' @@ -96,15 +92,15 @@ EXAMPLES = ''' venv: '/workspace/example/venv' pid: '/workspace/example/gunicorn.pid' user: 'ansible' -''' +""" -RETURN = ''' +RETURN = r""" gunicorn: - description: process id of gunicorn - returned: changed - type: str - sample: "1234" -''' + description: Process id of gunicorn. + returned: changed + type: str + sample: "1234" +""" import os import time