From 13e2097f378771d18df58b741d96020d56d5197c Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Thu, 26 Dec 2024 10:48:04 +1300 Subject: [PATCH] [pi ... prof]*: normalize docs (#9371) * [pi ... prof]*: normalize docs * Update plugins/modules/pkg5_publisher.py Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- plugins/modules/pids.py | 21 +- plugins/modules/pingdom.py | 81 ++++---- plugins/modules/pip_package_info.py | 25 +-- plugins/modules/pipx.py | 138 +++++++------- plugins/modules/pipx_info.py | 35 ++-- plugins/modules/pkg5.py | 19 +- plugins/modules/pkg5_publisher.py | 19 +- plugins/modules/pkgin.py | 108 +++++------ plugins/modules/pkgng.py | 179 +++++++++--------- plugins/modules/pkgutil.py | 49 +++-- plugins/modules/pmem.py | 148 +++++++-------- plugins/modules/pnpm.py | 34 ++-- plugins/modules/portage.py | 82 ++++---- plugins/modules/portinstall.py | 59 +++--- plugins/modules/pritunl_org.py | 71 ++++--- plugins/modules/pritunl_org_info.py | 33 ++-- plugins/modules/pritunl_user.py | 154 +++++++-------- plugins/modules/pritunl_user_info.py | 59 +++--- plugins/modules/profitbricks.py | 40 ++-- plugins/modules/profitbricks_datacenter.py | 27 ++- plugins/modules/profitbricks_nic.py | 27 ++- plugins/modules/profitbricks_volume.py | 35 ++-- .../profitbricks_volume_attachments.py | 25 ++- 23 files changed, 702 insertions(+), 766 deletions(-) diff --git a/plugins/modules/pids.py b/plugins/modules/pids.py index 99b52ef1dd..aea4d82d37 100644 --- a/plugins/modules/pids.py +++ b/plugins/modules/pids.py @@ -7,9 +7,10 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: pids -description: "Retrieves a list of PIDs of given process name in Ansible controller/controlled machines.Returns an empty list if no process in that name exists." +description: "Retrieves a list of PIDs of given process name in Ansible controller/controlled machines.Returns an empty list if no process in + that name exists." short_description: Retrieves process IDs list if the process is running otherwise return empty list author: - Saranya Sridharan (@saranyasridharan) @@ -35,13 +36,13 @@ options: type: bool default: false version_added: 3.0.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" # Pass the process name - name: Getting process IDs of the process community.general.pids: - name: python + name: python register: pids_of_python - name: Printing the process IDs obtained @@ -52,15 +53,15 @@ EXAMPLES = r''' community.general.pids: pattern: python(2(\.7)?|3(\.6)?)?\s+myapp\.py register: myapp_pids -''' +""" -RETURN = ''' +RETURN = r""" pids: - description: Process IDs of the given process + description: Process IDs of the given process. returned: list of none, one, or more process IDs type: list - sample: [100,200] -''' + sample: [100, 200] +""" import abc import re diff --git a/plugins/modules/pingdom.py b/plugins/modules/pingdom.py index bd4826a780..192dd244f2 100644 --- a/plugins/modules/pingdom.py +++ b/plugins/modules/pingdom.py @@ -8,56 +8,55 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - +DOCUMENTATION = r""" module: pingdom short_description: Pause/unpause Pingdom alerts description: - - This module will let you pause/unpause Pingdom alerts + - This module will let you pause/unpause Pingdom alerts. author: - - "Dylan Silva (@thaumos)" - - "Justin Johns (!UNKNOWN)" + - "Dylan Silva (@thaumos)" + - "Justin Johns (!UNKNOWN)" requirements: - - "This pingdom python library: https://github.com/mbabineau/pingdom-python" + - "This pingdom python library: U(https://github.com/mbabineau/pingdom-python)" extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - state: - type: str - description: - - Define whether or not the check should be running or paused. - required: true - choices: [ "running", "paused", "started", "stopped" ] - checkid: - type: str - description: - - Pingdom ID of the check. - required: true - uid: - type: str - description: - - Pingdom user ID. - required: true - passwd: - type: str - description: - - Pingdom user password. - required: true - key: - type: str - description: - - Pingdom API key. - required: true + state: + type: str + description: + - Define whether or not the check should be running or paused. + required: true + choices: ["running", "paused", "started", "stopped"] + checkid: + type: str + description: + - Pingdom ID of the check. + required: true + uid: + type: str + description: + - Pingdom user ID. + required: true + passwd: + type: str + description: + - Pingdom user password. + required: true + key: + type: str + description: + - Pingdom API key. + required: true notes: - - This module does not yet have support to add/remove checks. -''' + - This module does not yet have support to add/remove checks. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Pause the check with the ID of 12345 community.general.pingdom: uid: example@example.com @@ -73,7 +72,7 @@ EXAMPLES = ''' key: apipassword123 checkid: 12345 state: running -''' +""" import traceback diff --git a/plugins/modules/pip_package_info.py b/plugins/modules/pip_package_info.py index f7354e3678..0bc08e7ce1 100644 --- a/plugins/modules/pip_package_info.py +++ b/plugins/modules/pip_package_info.py @@ -9,33 +9,33 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = r""" module: pip_package_info short_description: Pip package information description: - - Return information about installed pip packages + - Return information about installed pip packages. extends_documentation_fragment: - community.general.attributes - community.general.attributes.info_module options: clients: description: - - A list of the pip executables that will be used to get the packages. - They can be supplied with the full path or just the executable name, for example V(pip3.7). + - A list of the pip executables that will be used to get the packages. They can be supplied with the full path or just the executable name, + for example V(pip3.7). default: ['pip'] required: false type: list elements: path requirements: - pip >= 20.3b1 (necessary for the C(--format) option) - - The requested pip executables must be installed on the target. + - The requested C(pip) executables must be installed on the target. author: - Matthew Jones (@matburt) - Brian Coca (@bcoca) - Adam Miller (@maxamillion) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Just get the list from default pip community.general.pip_package_info: @@ -46,16 +46,16 @@ EXAMPLES = ''' - name: Get from specific paths (virtualenvs?) community.general.pip_package_info: clients: '/home/me/projec42/python/pip3.5' -''' +""" -RETURN = ''' +RETURN = r""" packages: - description: a dictionary of installed package data + description: A dictionary of installed package data. returned: always type: dict contains: python: - description: A dictionary with each pip client which then contains a list of dicts with python package information + description: A dictionary with each pip client which then contains a list of dicts with python package information. returned: always type: dict sample: @@ -91,7 +91,8 @@ packages: ], }, } -''' +""" + import json import os diff --git a/plugins/modules/pipx.py b/plugins/modules/pipx.py index 1706f125d9..aa4309ce6c 100644 --- a/plugins/modules/pipx.py +++ b/plugins/modules/pipx.py @@ -9,16 +9,15 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pipx short_description: Manages applications installed with pipx version_added: 3.8.0 description: -- Manage Python applications installed in isolated virtualenvs using pipx. + - Manage Python applications installed in isolated virtualenvs using pipx. extends_documentation_fragment: -- community.general.attributes -- community.general.pipx + - community.general.attributes + - community.general.pipx attributes: check_mode: support: full @@ -28,131 +27,128 @@ options: state: type: str choices: - - present - - absent - - install - - install_all - - uninstall - - uninstall_all - - inject - - uninject - - upgrade - - upgrade_shared - - upgrade_all - - reinstall - - reinstall_all - - latest - - pin - - unpin + - present + - absent + - install + - install_all + - uninstall + - uninstall_all + - inject + - uninject + - upgrade + - upgrade_shared + - upgrade_all + - reinstall + - reinstall_all + - latest + - pin + - unpin default: install description: - - Desired state for the application. - - The states V(present) and V(absent) are aliases to V(install) and V(uninstall), respectively. - - The state V(latest) is equivalent to executing the task twice, with state V(install) and then V(upgrade). It was added in community.general - 5.5.0. - - The states V(install_all), V(uninject), V(upgrade_shared), V(pin) and V(unpin) are only available in C(pipx>=1.6.0), make sure to have a - compatible version when using this option. These states have been added in community.general 9.4.0. + - Desired state for the application. + - The states V(present) and V(absent) are aliases to V(install) and V(uninstall), respectively. + - The state V(latest) is equivalent to executing the task twice, with state V(install) and then V(upgrade). It was added in community.general + 5.5.0. + - The states V(install_all), V(uninject), V(upgrade_shared), V(pin) and V(unpin) are only available in C(pipx>=1.6.0), make sure to have + a compatible version when using this option. These states have been added in community.general 9.4.0. name: type: str description: - - The name of the application. In C(pipx) documentation it is also referred to as the name of the virtual environment where the application - will be installed. - - If O(name) is a simple package name without version specifiers, then that name is used as the Python package name to be installed. - - Use O(source) for passing package specifications or installing from URLs or directories. + - The name of the application. In C(pipx) documentation it is also referred to as the name of the virtual environment where the application + will be installed. + - If O(name) is a simple package name without version specifiers, then that name is used as the Python package name to be installed. + - Use O(source) for passing package specifications or installing from URLs or directories. source: type: str description: - - Source for the package. This option is used when O(state=install) or O(state=latest), and it is ignored with other states. - - Use O(source) when installing a Python package with version specifier, or from a local path, from a VCS URL or compressed file. - - The value of this option is passed as-is to C(pipx). - - O(name) is still required when using O(source) to establish the application name without fetching the package from a remote source. + - Source for the package. This option is used when O(state=install) or O(state=latest), and it is ignored with other states. + - Use O(source) when installing a Python package with version specifier, or from a local path, from a VCS URL or compressed file. + - The value of this option is passed as-is to C(pipx). + - O(name) is still required when using O(source) to establish the application name without fetching the package from a remote source. install_apps: description: - - Add apps from the injected packages. - - Only used when O(state=inject). + - Add apps from the injected packages. + - Only used when O(state=inject). type: bool default: false version_added: 6.5.0 install_deps: description: - - Include applications of dependent packages. - - Only used when O(state=install), O(state=latest), or O(state=inject). + - Include applications of dependent packages. + - Only used when O(state=install), O(state=latest), or O(state=inject). type: bool default: false inject_packages: description: - - Packages to be injected into an existing virtual environment. - - Only used when O(state=inject). + - Packages to be injected into an existing virtual environment. + - Only used when O(state=inject). type: list elements: str force: description: - - Force modification of the application's virtual environment. See C(pipx) for details. - - Only used when O(state=install), O(state=upgrade), O(state=upgrade_all), O(state=latest), or O(state=inject). + - Force modification of the application's virtual environment. See C(pipx) for details. + - Only used when O(state=install), O(state=upgrade), O(state=upgrade_all), O(state=latest), or O(state=inject). type: bool default: false include_injected: description: - - Upgrade the injected packages along with the application. - - Only used when O(state=upgrade), O(state=upgrade_all), or O(state=latest). - - This is used with O(state=upgrade) and O(state=latest) since community.general 6.6.0. + - Upgrade the injected packages along with the application. + - Only used when O(state=upgrade), O(state=upgrade_all), or O(state=latest). + - This is used with O(state=upgrade) and O(state=latest) since community.general 6.6.0. type: bool default: false index_url: description: - - Base URL of Python Package Index. - - Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject). + - Base URL of Python Package Index. + - Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject). type: str python: description: - - Python version to be used when creating the application virtual environment. Must be 3.6+. - - Only used when O(state=install), O(state=latest), O(state=reinstall), or O(state=reinstall_all). + - Python version to be used when creating the application virtual environment. Must be 3.6+. + - Only used when O(state=install), O(state=latest), O(state=reinstall), or O(state=reinstall_all). type: str system_site_packages: description: - - Give application virtual environment access to the system site-packages directory. - - Only used when O(state=install) or O(state=latest). + - Give application virtual environment access to the system site-packages directory. + - Only used when O(state=install) or O(state=latest). type: bool default: false version_added: 6.6.0 editable: description: - - Install the project in editable mode. + - Install the project in editable mode. type: bool default: false version_added: 4.6.0 pip_args: description: - - Arbitrary arguments to pass directly to C(pip). + - Arbitrary arguments to pass directly to C(pip). type: str version_added: 4.6.0 suffix: description: - - Optional suffix for virtual environment and executable names. - - "B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change." + - Optional suffix for virtual environment and executable names. + - B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change. type: str version_added: 9.3.0 global: version_added: 9.4.0 spec_metadata: description: - - Spec metadata file for O(state=install_all). - - This content of the file is usually generated with C(pipx list --json), and it can be obtained with M(community.general.pipx_info) with - O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output). + - Spec metadata file for O(state=install_all). + - This content of the file is usually generated with C(pipx list --json), and it can be obtained with M(community.general.pipx_info) with + O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output). type: path version_added: 9.4.0 notes: -- > - This first implementation does not verify whether a specified version constraint has been installed or not. - Hence, when using version operators, C(pipx) module will always try to execute the operation, - even when the application was previously installed. - This feature will be added in the future. + - This first implementation does not verify whether a specified version constraint has been installed or not. Hence, when using version operators, + C(pipx) module will always try to execute the operation, even when the application was previously installed. This feature will be added in + the future. author: -- "Alexei Znamensky (@russoz)" + - "Alexei Znamensky (@russoz)" """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: Install tox community.general.pipx: name: tox @@ -181,16 +177,16 @@ EXAMPLES = """ - name: Install multiple packages from list vars: pipx_packages: - - pycowsay - - black - - tox + - pycowsay + - black + - tox community.general.pipx: name: "{{ item }}" state: latest with_items: "{{ pipx_packages }}" """ -RETURN = """ +RETURN = r""" version: description: Version of pipx. type: str diff --git a/plugins/modules/pipx_info.py b/plugins/modules/pipx_info.py index 24a6739024..91d2fdb21c 100644 --- a/plugins/modules/pipx_info.py +++ b/plugins/modules/pipx_info.py @@ -9,46 +9,44 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pipx_info short_description: Rretrieves information about applications installed with pipx version_added: 5.6.0 description: -- Retrieve details about Python applications installed in isolated virtualenvs using pipx. + - Retrieve details about Python applications installed in isolated virtualenvs using pipx. extends_documentation_fragment: -- community.general.attributes -- community.general.attributes.info_module -- community.general.pipx + - community.general.attributes + - community.general.attributes.info_module + - community.general.pipx options: name: description: - - Name of an application installed with C(pipx). + - Name of an application installed with C(pipx). type: str include_deps: description: - - Include dependent packages in the output. + - Include dependent packages in the output. type: bool default: false include_injected: description: - - Include injected packages in the output. + - Include injected packages in the output. type: bool default: false include_raw: description: - - Returns the raw output of C(pipx list --json). - - The raw output is not affected by O(include_deps) or O(include_injected). + - Returns the raw output of C(pipx list --json). + - The raw output is not affected by O(include_deps) or O(include_injected). type: bool default: false global: version_added: 9.3.0 author: -- "Alexei Znamensky (@russoz)" + - "Alexei Znamensky (@russoz)" """ -EXAMPLES = """ ---- +EXAMPLES = r""" - name: retrieve all installed applications community.general.pipx_info: {} @@ -68,10 +66,9 @@ EXAMPLES = """ include_deps: true """ -RETURN = """ ---- +RETURN = r""" application: - description: The list of installed applications + description: The list of installed applications. returned: success type: list elements: dict @@ -100,8 +97,8 @@ application: licenses: "0.6.1" pinned: description: - - Whether the installed application is pinned or not. - - When using C(pipx<=1.6.0), this returns C(null). + - Whether the installed application is pinned or not. + - When using C(pipx<=1.6.0), this returns C(null). returned: success type: bool sample: diff --git a/plugins/modules/pkg5.py b/plugins/modules/pkg5.py index 08fa9272f7..34e86c3774 100644 --- a/plugins/modules/pkg5.py +++ b/plugins/modules/pkg5.py @@ -8,11 +8,10 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pkg5 author: -- Peter Oliver (@mavit) + - Peter Oliver (@mavit) short_description: Manages packages with the Solaris 11 Image Packaging System description: - IPS packages are the native packages in Solaris 11 and higher. @@ -36,7 +35,7 @@ options: state: description: - Whether to install (V(present), V(latest)), or remove (V(absent)) a package. - choices: [ absent, latest, present, installed, removed, uninstalled ] + choices: [absent, latest, present, installed, removed, uninstalled] default: present type: str accept_licenses: @@ -44,7 +43,7 @@ options: - Accept any licences. type: bool default: false - aliases: [ accept, accept_licences ] + aliases: [accept, accept_licences] be_name: description: - Creates a new boot environment with the given name. @@ -60,8 +59,8 @@ options: type: bool default: false version_added: 9.0.0 -''' -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Install Vim community.general.pkg5: name: editor/vim @@ -79,9 +78,9 @@ EXAMPLES = ''' - name: Install several packages at once community.general.pkg5: name: - - /file/gnu-findutils - - /text/gnu-grep -''' + - /file/gnu-findutils + - /text/gnu-grep +""" import re diff --git a/plugins/modules/pkg5_publisher.py b/plugins/modules/pkg5_publisher.py index 6d07e455f4..01c9d48cce 100644 --- a/plugins/modules/pkg5_publisher.py +++ b/plugins/modules/pkg5_publisher.py @@ -10,15 +10,13 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pkg5_publisher author: "Peter Oliver (@mavit)" short_description: Manages Solaris 11 Image Packaging System publishers description: - IPS packages are the native packages in Solaris 11 and higher. - - This modules will configure which publishers a client will download IPS - packages from. + - This modules will configure which publishers a client will download IPS packages from. extends_documentation_fragment: - community.general.attributes attributes: @@ -31,18 +29,17 @@ options: description: - The publisher's name. required: true - aliases: [ publisher ] + aliases: [publisher] type: str state: description: - Whether to ensure that a publisher is present or absent. default: present - choices: [ present, absent ] + choices: [present, absent] type: str sticky: description: - - Packages installed from a sticky repository can only receive updates - from that repository. + - Packages installed from a sticky repository can only receive updates from that repository. type: bool enabled: description: @@ -60,8 +57,8 @@ options: - Multiple values may be provided. type: list elements: str -''' -EXAMPLES = ''' +""" +EXAMPLES = r""" - name: Fetch packages for the solaris publisher direct from Oracle community.general.pkg5_publisher: name: solaris @@ -72,7 +69,7 @@ EXAMPLES = ''' community.general.pkg5_publisher: name: site origin: 'https://pkg.example.com/site/' -''' +""" from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pkgin.py b/plugins/modules/pkgin.py index 8b29655d37..76423f8135 100644 --- a/plugins/modules/pkgin.py +++ b/plugins/modules/pkgin.py @@ -16,70 +16,66 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pkgin short_description: Package manager for SmartOS, NetBSD, et al description: - - "The standard package manager for SmartOS, but also usable on NetBSD - or any OS that uses C(pkgsrc). (Home: U(http://pkgin.net/))" + - 'The standard package manager for SmartOS, but also usable on NetBSD or any OS that uses C(pkgsrc). (Home: U(http://pkgin.net/)).' author: - - "Larry Gilbert (@L2G)" - - "Shaun Zinck (@szinck)" - - "Jasper Lievisse Adriaanse (@jasperla)" + - "Larry Gilbert (@L2G)" + - "Shaun Zinck (@szinck)" + - "Jasper Lievisse Adriaanse (@jasperla)" notes: - - "Known bug with pkgin < 0.8.0: if a package is removed and another - package depends on it, the other package will be silently removed as - well." + - 'Known bug with pkgin < 0.8.0: if a package is removed and another package depends on it, the other package will be silently removed as well.' 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: - name: - description: - - Name of package to install/remove; - - multiple names may be given, separated by commas - aliases: [pkg] - type: list - elements: str - state: - description: - - Intended state of the package - choices: [ 'present', 'absent' ] - default: present - type: str - update_cache: - description: - - Update repository database. Can be run with other steps or on it's own. - type: bool - default: false - upgrade: - description: - - Upgrade main packages to their newer versions - type: bool - default: false - full_upgrade: - description: - - Upgrade all packages to their newer versions - type: bool - default: false - clean: - description: - - Clean packages cache - type: bool - default: false - force: - description: - - Force package reinstall - type: bool - default: false -''' + name: + description: + - Name of package to install/remove; + - Multiple names may be given, separated by commas. + aliases: [pkg] + type: list + elements: str + state: + description: + - Intended state of the package. + choices: ['present', 'absent'] + default: present + type: str + update_cache: + description: + - Update repository database. Can be run with other steps or on it's own. + type: bool + default: false + upgrade: + description: + - Upgrade main packages to their newer versions. + type: bool + default: false + full_upgrade: + description: + - Upgrade all packages to their newer versions. + type: bool + default: false + clean: + description: + - Clean packages cache. + type: bool + default: false + force: + description: + - Force package reinstall. + type: bool + default: false +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.pkgin: name: foo @@ -125,7 +121,7 @@ EXAMPLES = ''' - name: Clean packages cache (equivalent to pkgin clean) community.general.pkgin: clean: true -''' +""" import re diff --git a/plugins/modules/pkgng.py b/plugins/modules/pkgng.py index 7a04ee3a6e..ae333b492b 100644 --- a/plugins/modules/pkgng.py +++ b/plugins/modules/pkgng.py @@ -14,107 +14,100 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: pkgng short_description: Package manager for FreeBSD >= 9.0 description: - - Manage binary packages for FreeBSD using 'pkgng' which is available in versions after 9.0. + - Manage binary packages for FreeBSD using C(pkgng) which is available in versions after 9.0. 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: - name: - description: - - Name or list of names of packages to install/remove. - - "With O(name=*), O(state=latest) will operate, but O(state=present) and O(state=absent) will be noops." - required: true - aliases: [pkg] - type: list - elements: str - state: - description: - - State of the package. - choices: [ 'present', 'latest', 'absent' ] - required: false - default: present - type: str - cached: - description: - - Use local package base instead of fetching an updated one. - type: bool - required: false - default: false - annotation: - description: - - A list of keyvalue-pairs of the form - C(<+/-/:>[=]). A V(+) denotes adding an annotation, a - V(-) denotes removing an annotation, and V(:) denotes modifying an - annotation. - If setting or modifying annotations, a value must be provided. - required: false - type: list - elements: str - pkgsite: - description: - - For pkgng versions before 1.1.4, specify packagesite to use - for downloading packages. If not specified, use settings from - C(/usr/local/etc/pkg.conf). - - For newer pkgng versions, specify a the name of a repository - configured in C(/usr/local/etc/pkg/repos). - required: false - type: str - rootdir: - description: - - For pkgng versions 1.5 and later, pkg will install all packages - within the specified root directory. - - Can not be used together with O(chroot) or O(jail) options. - required: false - type: path - chroot: - description: - - Pkg will chroot in the specified environment. - - Can not be used together with O(rootdir) or O(jail) options. - required: false - type: path - jail: - description: - - Pkg will execute in the given jail name or id. - - Can not be used together with O(chroot) or O(rootdir) options. - type: str - autoremove: - description: - - Remove automatically installed packages which are no longer needed. - required: false - type: bool - default: false - ignore_osver: - description: - - Ignore FreeBSD OS version check, useful on -STABLE and -CURRENT branches. - - Defines the E(IGNORE_OSVERSION) environment variable. - required: false - type: bool - default: false - version_added: 1.3.0 - use_globs: - description: - - Treat the package names as shell glob patterns. - required: false - type: bool - default: true - version_added: 9.3.0 + name: + description: + - Name or list of names of packages to install/remove. + - With O(name=*), O(state=latest) will operate, but O(state=present) and O(state=absent) will be noops. + required: true + aliases: [pkg] + type: list + elements: str + state: + description: + - State of the package. + choices: ['present', 'latest', 'absent'] + required: false + default: present + type: str + cached: + description: + - Use local package base instead of fetching an updated one. + type: bool + required: false + default: false + annotation: + description: + - A list of keyvalue-pairs of the form C(<+/-/:>[=]). A V(+) denotes adding an annotation, a V(-) denotes removing an annotation, + and V(:) denotes modifying an annotation. If setting or modifying annotations, a value must be provided. + required: false + type: list + elements: str + pkgsite: + description: + - For C(pkgng) versions before 1.1.4, specify C(packagesite) to use for downloading packages. + If not specified, use settings from C(/usr/local/etc/pkg.conf). + - For newer C(pkgng) versions, specify a the name of a repository configured in C(/usr/local/etc/pkg/repos). + required: false + type: str + rootdir: + description: + - For C(pkgng) versions 1.5 and later, pkg will install all packages within the specified root directory. + - Can not be used together with O(chroot) or O(jail) options. + required: false + type: path + chroot: + description: + - Pkg will chroot in the specified environment. + - Can not be used together with O(rootdir) or O(jail) options. + required: false + type: path + jail: + description: + - Pkg will execute in the given jail name or id. + - Can not be used together with O(chroot) or O(rootdir) options. + type: str + autoremove: + description: + - Remove automatically installed packages which are no longer needed. + required: false + type: bool + default: false + ignore_osver: + description: + - Ignore FreeBSD OS version check, useful on C(-STABLE) and C(-CURRENT) branches. + - Defines the E(IGNORE_OSVERSION) environment variable. + required: false + type: bool + default: false + version_added: 1.3.0 + use_globs: + description: + - Treat the package names as shell glob patterns. + required: false + type: bool + default: true + version_added: 9.3.0 author: "bleader (@bleader)" notes: - - When using pkgsite, be careful that already in cache packages won't be downloaded again. - - When used with a C(loop:) each package will be processed individually, - it is much more efficient to pass the list directly to the O(name) option. -''' + - When using pkgsite, be careful that already in cache packages will not be downloaded again. + - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) + option. +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.pkgng: name: foo @@ -149,7 +142,7 @@ EXAMPLES = ''' name: foo/bar state: latest use_globs: false -''' +""" from collections import defaultdict diff --git a/plugins/modules/pkgutil.py b/plugins/modules/pkgutil.py index 15f98a9d49..ce85308651 100644 --- a/plugins/modules/pkgutil.py +++ b/plugins/modules/pkgutil.py @@ -12,19 +12,18 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: pkgutil short_description: OpenCSW package management on Solaris description: -- This module installs, updates and removes packages from the OpenCSW project for Solaris. -- Unlike the M(community.general.svr4pkg) module, it will resolve and download dependencies. -- See U(https://www.opencsw.org/) for more information about the project. + - This module installs, updates and removes packages from the OpenCSW project for Solaris. + - Unlike the M(community.general.svr4pkg) module, it will resolve and download dependencies. + - See U(https://www.opencsw.org/) for more information about the project. author: -- Alexander Winkler (@dermute) -- David Ponessa (@scathatheworm) + - Alexander Winkler (@dermute) + - David Ponessa (@scathatheworm) extends_documentation_fragment: -- community.general.attributes + - community.general.attributes attributes: check_mode: support: full @@ -35,40 +34,40 @@ attributes: options: name: description: - - The name of the package. - - When using O(state=latest), this can be V('*'), which updates all installed packages managed by pkgutil. + - The name of the package. + - When using O(state=latest), this can be V('*'), which updates all installed packages managed by pkgutil. type: list required: true elements: str - aliases: [ pkg ] + aliases: [pkg] site: description: - - The repository path to install the package from. - - Its global definition is in C(/etc/opt/csw/pkgutil.conf). + - The repository path to install the package from. + - Its global definition is in C(/etc/opt/csw/pkgutil.conf). required: false type: str state: description: - - Whether to install (V(present)/V(installed)), or remove (V(absent)/V(removed)) packages. - - The upgrade (V(latest)) operation will update/install the packages to the latest version available. + - Whether to install (V(present)/V(installed)), or remove (V(absent)/V(removed)) packages. + - The upgrade (V(latest)) operation will update/install the packages to the latest version available. type: str required: true - choices: [ absent, installed, latest, present, removed ] + choices: [absent, installed, latest, present, removed] update_catalog: description: - - If you always want to refresh your catalog from the mirror, even when it's not stale, set this to V(true). + - If you always want to refresh your catalog from the mirror, even when it's not stale, set this to V(true). type: bool default: false force: description: - - To allow the update process to downgrade packages to match what is present in the repository, set this to V(true). - - This is useful for rolling back to stable from testing, or similar operations. + - To allow the update process to downgrade packages to match what is present in the repository, set this to V(true). + - This is useful for rolling back to stable from testing, or similar operations. type: bool default: false version_added: 1.2.0 -''' +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Install a package community.general.pkgutil: name: CSWcommon @@ -88,8 +87,8 @@ EXAMPLES = r''' - name: Install several packages community.general.pkgutil: name: - - CSWsudo - - CSWtop + - CSWsudo + - CSWtop state: present - name: Update all packages @@ -102,9 +101,9 @@ EXAMPLES = r''' name: '*' state: latest force: true -''' +""" -RETURN = r''' # ''' +RETURN = r""" # """ from ansible.module_utils.basic import AnsibleModule diff --git a/plugins/modules/pmem.py b/plugins/modules/pmem.py index 4d10c448e1..4e6edfeb06 100644 --- a/plugins/modules/pmem.py +++ b/plugins/modules/pmem.py @@ -7,21 +7,19 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" author: - - Masayoshi Mizuma (@mizumm) + - Masayoshi Mizuma (@mizumm) module: pmem short_description: Configure Intel Optane Persistent Memory modules version_added: 4.5.0 description: - - This module allows Configuring Intel Optane Persistent Memory modules - (PMem) using ipmctl and ndctl command line tools. + - This module allows Configuring Intel Optane Persistent Memory modules (PMem) using C(ipmctl) and C(ndctl) command line tools. requirements: - - ipmctl and ndctl command line tools - - xmltodict + - C(ipmctl) and C(ndctl) command line tools + - xmltodict extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: check_mode: support: none @@ -30,33 +28,31 @@ attributes: options: appdirect: description: - - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)). - - Create AppDirect capacity utilizing hardware interleaving across the - requested PMem modules if applicable given the specified target. - - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100) + - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)). + - Create AppDirect capacity utilizing hardware interleaving across the requested PMem modules if applicable given the specified target. + - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100). type: int appdirect_interleaved: description: - - Create AppDirect capacity that is interleaved any other PMem modules. + - Create AppDirect capacity that is interleaved any other PMem modules. type: bool required: false default: true memorymode: description: - - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)). + - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)). type: int reserved: description: - - Percentage of the capacity to reserve (V(0)-V(100)). O(reserved) will not be mapped - into the system physical address space and will be presented as reserved - capacity with Show Device and Show Memory Resources Commands. - - O(reserved) will be set automatically if this is not configured. + - Percentage of the capacity to reserve (V(0)-V(100)). O(reserved) will not be mapped into the system physical address space and will be + presented as reserved capacity with Show Device and Show Memory Resources Commands. + - O(reserved) will be set automatically if this is not configured. type: int required: false socket: description: - - This enables to set the configuration for each socket by using the socket ID. - - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100) within one socket. + - This enables to set the configuration for each socket by using the socket ID. + - Total of O(appdirect), O(memorymode) and O(reserved) must be V(100) within one socket. type: list elements: dict suboptions: @@ -66,18 +62,18 @@ options: required: true appdirect: description: - - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)) within the socket ID. + - Percentage of the total capacity to use in AppDirect Mode (V(0)-V(100)) within the socket ID. type: int required: true appdirect_interleaved: description: - - Create AppDirect capacity that is interleaved any other PMem modules within the socket ID. + - Create AppDirect capacity that is interleaved any other PMem modules within the socket ID. type: bool required: false default: true memorymode: description: - - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)) within the socket ID. + - Percentage of the total capacity to use in Memory Mode (V(0)-V(100)) within the socket ID. type: int required: true reserved: @@ -86,86 +82,86 @@ options: type: int namespace: description: - - This enables to set the configuration for the namespace of the PMem. + - This enables to set the configuration for the namespace of the PMem. type: list elements: dict suboptions: mode: description: - - The mode of namespace. The detail of the mode is in the man page of ndctl-create-namespace. + - The mode of namespace. The detail of the mode is in the man page of ndctl-create-namespace. type: str required: true choices: ['raw', 'sector', 'fsdax', 'devdax'] type: description: - - The type of namespace. The detail of the type is in the man page of ndctl-create-namespace. + - The type of namespace. The detail of the type is in the man page of ndctl-create-namespace. type: str required: false choices: ['pmem', 'blk'] size: description: - - The size of namespace. This option supports the suffixes V(k) or V(K) or V(KB) for KiB, - V(m) or V(M) or V(MB) for MiB, V(g) or V(G) or V(GB) for GiB and V(t) or V(T) or V(TB) for TiB. + - The size of namespace. This option supports the suffixes V(k) or V(K) or V(KB) for KiB, V(m) or V(M) or V(MB) for MiB, V(g) or V(G) + or V(GB) for GiB and V(t) or V(T) or V(TB) for TiB. - This option is required if multiple namespaces are configured. - If this option is not set, all of the available space of a region is configured. type: str required: false namespace_append: description: - - Enable to append the new namespaces to the system. - - The default is V(false) so the all existing namespaces not listed in O(namespace) are removed. + - Enable to append the new namespaces to the system. + - The default is V(false) so the all existing namespaces not listed in O(namespace) are removed. type: bool default: false required: false -''' +""" -RETURN = r''' +RETURN = r""" reboot_required: - description: Indicates that the system reboot is required to complete the PMem configuration. - returned: success - type: bool - sample: true + description: Indicates that the system reboot is required to complete the PMem configuration. + returned: success + type: bool + sample: true result: - description: - - Shows the value of AppDirect, Memory Mode and Reserved size in bytes. - - If O(socket) argument is provided, shows the values in each socket with C(socket) which contains the socket ID. - - If O(namespace) argument is provided, shows the detail of each namespace. - returned: success - type: list - elements: dict - contains: - appdirect: - description: AppDirect size in bytes. - type: int - memorymode: - description: Memory Mode size in bytes. - type: int - reserved: - description: Reserved size in bytes. - type: int - socket: - description: The socket ID to be configured. - type: int - namespace: - description: The list of the detail of namespace. - type: list - sample: [ - { - "appdirect": 111669149696, - "memorymode": 970662608896, - "reserved": 3626500096, - "socket": 0 - }, - { - "appdirect": 111669149696, - "memorymode": 970662608896, - "reserved": 3626500096, - "socket": 1 - } - ] -''' + description: + - Shows the value of AppDirect, Memory Mode and Reserved size in bytes. + - If O(socket) argument is provided, shows the values in each socket with C(socket) which contains the socket ID. + - If O(namespace) argument is provided, shows the detail of each namespace. + returned: success + type: list + elements: dict + contains: + appdirect: + description: AppDirect size in bytes. + type: int + memorymode: + description: Memory Mode size in bytes. + type: int + reserved: + description: Reserved size in bytes. + type: int + socket: + description: The socket ID to be configured. + type: int + namespace: + description: The list of the detail of namespace. + type: list + sample: [ + { + "appdirect": 111669149696, + "memorymode": 970662608896, + "reserved": 3626500096, + "socket": 0 + }, + { + "appdirect": 111669149696, + "memorymode": 970662608896, + "reserved": 3626500096, + "socket": 1 + } + ] +""" -EXAMPLES = r''' +EXAMPLES = r""" - name: Configure the Pmem as AppDirect 10, Memory Mode 70, and the Reserved 20 percent. community.general.pmem: appdirect: 10 @@ -205,7 +201,7 @@ EXAMPLES = r''' - size: 320MB type: pmem mode: sector -''' +""" import json import re diff --git a/plugins/modules/pnpm.py b/plugins/modules/pnpm.py index 315b07ba8e..c4dbf55dff 100644 --- a/plugins/modules/pnpm.py +++ b/plugins/modules/pnpm.py @@ -12,13 +12,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pnpm -short_description: Manage node.js packages with pnpm +short_description: Manage Node.js packages with C(pnpm) version_added: 7.4.0 description: - - Manage node.js packages with the L(pnpm package manager, https://pnpm.io/). + - Manage Node.js packages with the L(pnpm package manager, https://pnpm.io/). author: - "Aritra Sen (@aretrosen)" - "Chris Hoffman (@chrishoffman), creator of NPM Ansible module" @@ -32,18 +31,18 @@ attributes: options: name: description: - - The name of a node.js library to install. - - All packages in package.json are installed if not provided. + - The name of a Node.js library to install. + - All packages in C(package.json) are installed if not provided. type: str required: false alias: description: - - Alias of the node.js library. + - Alias of the Node.js library. type: str required: false path: description: - - The base path to install the node.js libraries. + - The base path to install the Node.js libraries. type: path required: false version: @@ -53,7 +52,7 @@ options: required: false global: description: - - Install the node.js library globally. + - Install the Node.js library globally. required: false default: false type: bool @@ -97,7 +96,7 @@ options: type: bool state: description: - - Installation state of the named node.js library. + - Installation state of the named Node.js library. - If V(absent) is selected, a name option must be provided. type: str required: false @@ -107,36 +106,36 @@ requirements: - Pnpm executable present in E(PATH). """ -EXAMPLES = """ -- name: Install "tailwindcss" node.js package. +EXAMPLES = r""" +- name: Install "tailwindcss" Node.js package. community.general.pnpm: name: tailwindcss path: /app/location -- name: Install "tailwindcss" node.js package on version 3.3.2 +- name: Install "tailwindcss" Node.js package on version 3.3.2 community.general.pnpm: name: tailwindcss version: 3.3.2 path: /app/location -- name: Install "tailwindcss" node.js package globally. +- name: Install "tailwindcss" Node.js package globally. community.general.pnpm: name: tailwindcss global: true -- name: Install "tailwindcss" node.js package as dev dependency. +- name: Install "tailwindcss" Node.js package as dev dependency. community.general.pnpm: name: tailwindcss path: /app/location dev: true -- name: Install "tailwindcss" node.js package as optional dependency. +- name: Install "tailwindcss" Node.js package as optional dependency. community.general.pnpm: name: tailwindcss path: /app/location optional: true -- name: Install "tailwindcss" node.js package version 0.1.3 as tailwind-1 +- name: Install "tailwindcss" Node.js package version 0.1.3 as tailwind-1 community.general.pnpm: name: tailwindcss alias: tailwind-1 @@ -158,6 +157,7 @@ EXAMPLES = """ path: /app/location state: latest """ + import json import os diff --git a/plugins/modules/portage.py b/plugins/modules/portage.py index 8ae8efb087..f0b7220836 100644 --- a/plugins/modules/portage.py +++ b/plugins/modules/portage.py @@ -14,13 +14,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: portage short_description: Package manager for Gentoo description: - - Manages Gentoo packages - + - Manages Gentoo packages. extends_documentation_fragment: - community.general.attributes @@ -33,21 +31,21 @@ attributes: options: package: description: - - Package atom or set, for example V(sys-apps/foo) or V(>foo-2.13) or V(@world) + - Package atom or set, for example V(sys-apps/foo) or V(>foo-2.13) or V(@world). aliases: [name] type: list elements: str state: description: - - State of the package atom + - State of the package atom. default: "present" - choices: [ "present", "installed", "emerged", "absent", "removed", "unmerged", "latest" ] + choices: ["present", "installed", "emerged", "absent", "removed", "unmerged", "latest"] type: str update: description: - - Update packages to the best version available (--update) + - Update packages to the best version available (C(--update)). type: bool default: false @@ -59,82 +57,81 @@ options: deep: description: - - Consider the entire dependency tree of packages (--deep) + - Consider the entire dependency tree of packages (C(--deep)). type: bool default: false newuse: description: - - Include installed packages where USE flags have changed (--newuse) + - Include installed packages where USE flags have changed (C(--newuse)). type: bool default: false changed_use: description: - - Include installed packages where USE flags have changed, except when - - flags that the user has not enabled are added or removed - - (--changed-use) + - Include installed packages where USE flags have changed, except when. + - Flags that the user has not enabled are added or removed. + - (C(--changed-use)). type: bool default: false oneshot: description: - - Do not add the packages to the world file (--oneshot) + - Do not add the packages to the world file (C(--oneshot)). type: bool default: false noreplace: description: - - Do not re-emerge installed packages (--noreplace) + - Do not re-emerge installed packages (C(--noreplace)). type: bool default: true nodeps: description: - - Only merge packages but not their dependencies (--nodeps) + - Only merge packages but not their dependencies (C(--nodeps)). type: bool default: false onlydeps: description: - - Only merge packages' dependencies but not the packages (--onlydeps) + - Only merge packages' dependencies but not the packages (C(--onlydeps)). type: bool default: false depclean: description: - - Remove packages not needed by explicitly merged packages (--depclean) - - If no package is specified, clean up the world's dependencies - - Otherwise, --depclean serves as a dependency aware version of --unmerge + - Remove packages not needed by explicitly merged packages (C(--depclean)). + - If no package is specified, clean up the world's dependencies. + - Otherwise, C(--depclean) serves as a dependency aware version of C(--unmerge). type: bool default: false quiet: description: - - Run emerge in quiet mode (--quiet) + - Run emerge in quiet mode (C(--quiet)). type: bool default: false verbose: description: - - Run emerge in verbose mode (--verbose) + - Run emerge in verbose mode (C(--verbose)). type: bool default: false select: description: - If set to V(true), explicitely add the package to the world file. - - Please note that this option is not used for idempotency, it is only used - when actually installing a package. + - Please note that this option is not used for idempotency, it is only used when actually installing a package. type: bool version_added: 8.6.0 sync: description: - - Sync package repositories first - - If V(yes), perform "emerge --sync" - - If V(web), perform "emerge-webrsync" - choices: [ "web", "yes", "no" ] + - Sync package repositories first. + - If V(yes), perform C(emerge --sync). + - If V(web), perform C(emerge-webrsync). + choices: ["web", "yes", "no"] type: str getbinpkgonly: @@ -171,16 +168,13 @@ options: jobs: description: - Specifies the number of packages to build simultaneously. - - "Since version 2.6: Value of 0 or False resets any previously added" - - --jobs setting values + - 'Since version 2.6: Value of V(0) or V(false) resets any previously added C(--jobs) setting values.' type: int loadavg: description: - - Specifies that no new builds should be started if there are - - other builds running and the load average is at least LOAD - - "Since version 2.6: Value of 0 or False resets any previously added" - - --load-average setting values + - Specifies that no new builds should be started if there are other builds running and the load average is at least LOAD. + - 'Since version 2.6: Value of 0 or False resets any previously added C(--load-average) setting values.' type: float withbdeps: @@ -191,26 +185,24 @@ options: quietbuild: description: - - Redirect all build output to logs alone, and do not display it - - on stdout (--quiet-build) + - Redirect all build output to logs alone, and do not display it on stdout (C(--quiet-build)). type: bool default: false quietfail: description: - - Suppresses display of the build log on stdout (--quiet-fail) - - Only the die message and the path of the build log will be - - displayed on stdout. + - Suppresses display of the build log on stdout (--quiet-fail). + - Only the die message and the path of the build log will be displayed on stdout. type: bool default: false author: - - "William L Thomson Jr (@wltjr)" - - "Yap Sok Ann (@sayap)" - - "Andrew Udvare (@Tatsh)" -''' + - "William L Thomson Jr (@wltjr)" + - "Yap Sok Ann (@sayap)" + - "Andrew Udvare (@Tatsh)" +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Make sure package foo is installed community.general.portage: package: foo @@ -252,7 +244,7 @@ EXAMPLES = ''' package: foo state: absent depclean: true -''' +""" import os import re diff --git a/plugins/modules/portinstall.py b/plugins/modules/portinstall.py index 59dafb1eb8..d4e1591d32 100644 --- a/plugins/modules/portinstall.py +++ b/plugins/modules/portinstall.py @@ -12,43 +12,42 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: portinstall short_description: Installing packages from FreeBSD's ports system description: - - Manage packages for FreeBSD using 'portinstall'. + - Manage packages for FreeBSD using C(portinstall). extends_documentation_fragment: - - community.general.attributes + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - description: - - name of package to install/remove - aliases: [pkg] - required: true - type: str - state: - description: - - state of the package - choices: [ 'present', 'absent' ] - required: false - default: present - type: str - use_packages: - description: - - use packages instead of ports whenever available - type: bool - required: false - default: true + name: + description: + - Name of package to install/remove. + aliases: [pkg] + required: true + type: str + state: + description: + - State of the package. + choices: ['present', 'absent'] + required: false + default: present + type: str + use_packages: + description: + - Use packages instead of ports whenever available. + type: bool + required: false + default: true author: "berenddeboer (@berenddeboer)" -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Install package foo community.general.portinstall: name: foo @@ -63,7 +62,7 @@ EXAMPLES = ''' community.general.portinstall: name: foo,bar state: absent -''' +""" import re diff --git a/plugins/modules/pritunl_org.py b/plugins/modules/pritunl_org.py index 4945a8fc20..d97f9567cd 100644 --- a/plugins/modules/pritunl_org.py +++ b/plugins/modules/pritunl_org.py @@ -8,54 +8,47 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pritunl_org author: Florian Dambrine (@Lowess) version_added: 2.5.0 short_description: Manages Pritunl Organizations using the Pritunl API description: - - A module to manage Pritunl organizations using the Pritunl API. + - A module to manage Pritunl organizations using the Pritunl API. extends_documentation_fragment: - - community.general.pritunl - - community.general.attributes + - community.general.pritunl + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - name: - type: str - required: true - aliases: - - org - description: - - The name of the organization to manage in Pritunl. - - force: - type: bool - default: false - description: - - If O(force) is V(true) and O(state) is V(absent), the module - will delete the organization, no matter if it contains users - or not. By default O(force) is V(false), which will cause the - module to fail the deletion of the organization when it contains - users. - - state: - type: str - default: 'present' - choices: - - present - - absent - description: - - If V(present), the module adds organization O(name) to - Pritunl. If V(absent), attempt to delete the organization - from Pritunl (please read about O(force) usage). + name: + type: str + required: true + aliases: + - org + description: + - The name of the organization to manage in Pritunl. + force: + type: bool + default: false + description: + - If O(force) is V(true) and O(state) is V(absent), the module will delete the organization, no matter if it contains users or not. By default + O(force) is V(false), which will cause the module to fail the deletion of the organization when it contains users. + state: + type: str + default: 'present' + choices: + - present + - absent + description: + - If V(present), the module adds organization O(name) to Pritunl. If V(absent), attempt to delete the organization from Pritunl (please + read about O(force) usage). """ -EXAMPLES = """ +EXAMPLES = r""" - name: Ensure the organization named MyOrg exists community.general.pritunl_org: state: present @@ -67,7 +60,7 @@ EXAMPLES = """ name: MyOrg """ -RETURN = """ +RETURN = r""" response: description: JSON representation of a Pritunl Organization. returned: success diff --git a/plugins/modules/pritunl_org_info.py b/plugins/modules/pritunl_org_info.py index 979e29b5a0..dc198bc9cc 100644 --- a/plugins/modules/pritunl_org_info.py +++ b/plugins/modules/pritunl_org_info.py @@ -8,32 +8,29 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pritunl_org_info author: Florian Dambrine (@Lowess) version_added: 2.5.0 short_description: List Pritunl Organizations using the Pritunl API description: - - A module to list Pritunl organizations using the Pritunl API. + - A module to list Pritunl organizations using the Pritunl API. extends_documentation_fragment: - - community.general.pritunl - - community.general.attributes - - community.general.attributes.info_module + - community.general.pritunl + - community.general.attributes + - community.general.attributes.info_module options: - organization: - type: str - required: false - aliases: - - org - default: null - description: - - Name of the Pritunl organization to search for. - If none provided, the module will return all Pritunl - organizations. + organization: + type: str + required: false + aliases: + - org + default: null + description: + - Name of the Pritunl organization to search for. If none provided, the module will return all Pritunl organizations. """ -EXAMPLES = """ +EXAMPLES = r""" - name: List all existing Pritunl organizations community.general.pritunl_org_info: @@ -42,7 +39,7 @@ EXAMPLES = """ organization: MyOrg """ -RETURN = """ +RETURN = r""" organizations: description: List of Pritunl organizations. returned: success diff --git a/plugins/modules/pritunl_user.py b/plugins/modules/pritunl_user.py index bdbc335d90..932c4c1322 100644 --- a/plugins/modules/pritunl_user.py +++ b/plugins/modules/pritunl_user.py @@ -8,97 +8,87 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pritunl_user author: "Florian Dambrine (@Lowess)" version_added: 2.3.0 short_description: Manage Pritunl Users using the Pritunl API description: - - A module to manage Pritunl users using the Pritunl API. + - A module to manage Pritunl users using the Pritunl API. extends_documentation_fragment: - - community.general.pritunl - - community.general.attributes + - community.general.pritunl + - community.general.attributes attributes: - check_mode: - support: none - diff_mode: - support: none + check_mode: + support: none + diff_mode: + support: none options: - organization: - type: str - required: true - aliases: - - org - description: - - The name of the organization the user is part of. - - state: - type: str - default: 'present' - choices: - - present - - absent - description: - - If V(present), the module adds user O(user_name) to - the Pritunl O(organization). If V(absent), removes the user - O(user_name) from the Pritunl O(organization). - - user_name: - type: str - required: true - default: null - description: - - Name of the user to create or delete from Pritunl. - - user_email: - type: str - required: false - default: null - description: - - Email address associated with the user O(user_name). - - user_type: - type: str - required: false - default: client - choices: - - client - - server - description: - - Type of the user O(user_name). - - user_groups: - type: list - elements: str - required: false - default: null - description: - - List of groups associated with the user O(user_name). - - user_disabled: - type: bool - required: false - default: null - description: - - Enable/Disable the user O(user_name). - - user_gravatar: - type: bool - required: false - default: null - description: - - Enable/Disable Gravatar usage for the user O(user_name). - - user_mac_addresses: - type: list - elements: str - description: - - Allowed MAC addresses for the user O(user_name). - version_added: 5.0.0 + organization: + type: str + required: true + aliases: + - org + description: + - The name of the organization the user is part of. + state: + type: str + default: 'present' + choices: + - present + - absent + description: + - If V(present), the module adds user O(user_name) to the Pritunl O(organization). If V(absent), removes the user O(user_name) from the + Pritunl O(organization). + user_name: + type: str + required: true + default: + description: + - Name of the user to create or delete from Pritunl. + user_email: + type: str + required: false + default: + description: + - Email address associated with the user O(user_name). + user_type: + type: str + required: false + default: client + choices: + - client + - server + description: + - Type of the user O(user_name). + user_groups: + type: list + elements: str + required: false + default: + description: + - List of groups associated with the user O(user_name). + user_disabled: + type: bool + required: false + default: + description: + - Enable/Disable the user O(user_name). + user_gravatar: + type: bool + required: false + default: + description: + - Enable/Disable Gravatar usage for the user O(user_name). + user_mac_addresses: + type: list + elements: str + description: + - Allowed MAC addresses for the user O(user_name). + version_added: 5.0.0 """ -EXAMPLES = """ +EXAMPLES = r""" - name: Create the user Foo with email address foo@bar.com in MyOrg community.general.pritunl_user: state: present @@ -123,7 +113,7 @@ EXAMPLES = """ user_name: Foo """ -RETURN = """ +RETURN = r""" response: description: JSON representation of Pritunl Users. returned: success diff --git a/plugins/modules/pritunl_user_info.py b/plugins/modules/pritunl_user_info.py index 3f8f62003f..02d8512315 100644 --- a/plugins/modules/pritunl_user_info.py +++ b/plugins/modules/pritunl_user_info.py @@ -8,45 +8,42 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = """ ---- +DOCUMENTATION = r""" module: pritunl_user_info author: "Florian Dambrine (@Lowess)" version_added: 2.3.0 short_description: List Pritunl Users using the Pritunl API description: - - A module to list Pritunl users using the Pritunl API. + - A module to list Pritunl users using the Pritunl API. extends_documentation_fragment: - - community.general.pritunl - - community.general.attributes - - community.general.attributes.info_module + - community.general.pritunl + - community.general.attributes + - community.general.attributes.info_module options: - organization: - type: str - required: true - aliases: - - org - description: - - The name of the organization the user is part of. - - user_name: - type: str - required: false - description: - - Name of the user to filter on Pritunl. - - user_type: - type: str - required: false - default: client - choices: - - client - - server - description: - - Type of the user O(user_name). + organization: + type: str + required: true + aliases: + - org + description: + - The name of the organization the user is part of. + user_name: + type: str + required: false + description: + - Name of the user to filter on Pritunl. + user_type: + type: str + required: false + default: client + choices: + - client + - server + description: + - Type of the user O(user_name). """ -EXAMPLES = """ +EXAMPLES = r""" - name: List all existing users part of the organization MyOrg community.general.pritunl_user_info: state: list @@ -59,7 +56,7 @@ EXAMPLES = """ user_name: Florian """ -RETURN = """ +RETURN = r""" users: description: List of Pritunl users. returned: success diff --git a/plugins/modules/profitbricks.py b/plugins/modules/profitbricks.py index 875bd78c4e..e912db6985 100644 --- a/plugins/modules/profitbricks.py +++ b/plugins/modules/profitbricks.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: profitbricks short_description: Create, destroy, start, stop, and reboot a ProfitBricks virtual machine description: - - Create, destroy, update, start, stop, and reboot a ProfitBricks virtual machine. When the virtual machine is created it can optionally wait - for it to be 'running' before returning. This module has a dependency on profitbricks >= 1.0.0 + - Create, destroy, update, start, stop, and reboot a ProfitBricks virtual machine. When the virtual machine is created it can optionally wait + for it to be 'running' before returning. This module has a dependency on profitbricks >= 1.0.0. extends_documentation_fragment: - community.general.attributes attributes: @@ -34,7 +33,7 @@ options: type: str image: description: - - The system image ID for creating the virtual machine, e.g. a3eae284-a2fe-11e4-b187-5f1f641608c8. + - The system image ID for creating the virtual machine, for example V(a3eae284-a2fe-11e4-b187-5f1f641608c8). type: str image_password: description: @@ -65,7 +64,7 @@ options: - The CPU family type to allocate to the virtual machine. type: str default: AMD_OPTERON - choices: [ "AMD_OPTERON", "INTEL_XEON" ] + choices: ["AMD_OPTERON", "INTEL_XEON"] volume_size: description: - The size in GB of the boot volume. @@ -76,10 +75,10 @@ options: - The bus type for the volume. type: str default: VIRTIO - choices: [ "IDE", "VIRTIO"] + choices: ["IDE", "VIRTIO"] instance_ids: description: - - list of instance ids, currently only used when state='absent' to remove instances. + - List of instance ids, currently only used when state='absent' to remove instances. type: list elements: str default: [] @@ -93,7 +92,7 @@ options: - The datacenter location. Use only if you want to create the Datacenter or else this value is ignored. type: str default: us/las - choices: [ "us/las", "de/fra", "de/fkb" ] + choices: ["us/las", "de/fra", "de/fkb"] assign_public_ip: description: - This will assign the machine to the public LAN. If no LAN exists with public Internet access it is created. @@ -106,47 +105,46 @@ options: default: 1 subscription_user: description: - - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable. + - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable. type: str subscription_password: description: - - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable. + - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable. type: str wait: description: - - wait for the instance to be in state 'running' before returning + - Wait for the instance to be in state 'running' before returning. type: bool default: true wait_timeout: description: - - how long before wait gives up, in seconds + - How long before wait gives up, in seconds. type: int default: 600 remove_boot_volume: description: - - remove the bootVolume of the virtual machine you're destroying. + - Remove the bootVolume of the virtual machine you are destroying. type: bool default: true state: description: - - create or terminate instances + - Create or terminate instances. - 'The choices available are: V(running), V(stopped), V(absent), V(present).' type: str default: 'present' disk_type: description: - - the type of disk to be allocated. + - The type of disk to be allocated. type: str choices: [SSD, HDD] default: HDD requirements: - - "profitbricks" + - "profitbricks" author: Matt Baldwin (@baldwinSPC) -''' - -EXAMPLES = ''' +""" +EXAMPLES = r""" # Note: These examples do not set authentication details, see the AWS Guide for details. # Provisioning example @@ -192,7 +190,7 @@ EXAMPLES = ''' - 'web003.stackpointcloud.com' wait_timeout: 500 state: stopped -''' +""" import re import uuid diff --git a/plugins/modules/profitbricks_datacenter.py b/plugins/modules/profitbricks_datacenter.py index 4aa1fa5eeb..93c27b5d8d 100644 --- a/plugins/modules/profitbricks_datacenter.py +++ b/plugins/modules/profitbricks_datacenter.py @@ -8,13 +8,12 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: profitbricks_datacenter short_description: Create or destroy a ProfitBricks Virtual Datacenter description: - - This is a simple module that supports creating or removing vDCs. A vDC is required before you can create servers. This module has a dependency - on profitbricks >= 1.0.0 + - This is a simple module that supports creating or removing vDCs. A vDC is required before you can create servers. This module has a dependency + on profitbricks >= 1.0.0. extends_documentation_fragment: - community.general.attributes attributes: @@ -38,41 +37,41 @@ options: type: str required: false default: us/las - choices: [ "us/las", "de/fra", "de/fkb" ] + choices: ["us/las", "de/fra", "de/fkb"] subscription_user: description: - - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable. + - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable. type: str required: false subscription_password: description: - - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable. + - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable. type: str required: false wait: description: - - wait for the datacenter to be created before returning + - Wait for the datacenter to be created before returning. required: false default: true type: bool wait_timeout: description: - - how long before wait gives up, in seconds + - How long before wait gives up, in seconds. type: int default: 600 state: description: - Create or terminate datacenters. - - "The available choices are: V(present), V(absent)." + - 'The available choices are: V(present), V(absent).' type: str required: false default: 'present' -requirements: [ "profitbricks" ] +requirements: ["profitbricks"] author: Matt Baldwin (@baldwinSPC) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a datacenter community.general.profitbricks_datacenter: datacenter: Tardis One @@ -83,7 +82,7 @@ EXAMPLES = ''' datacenter: Tardis One wait_timeout: 500 state: absent -''' +""" import re import time diff --git a/plugins/modules/profitbricks_nic.py b/plugins/modules/profitbricks_nic.py index 9498be15dc..0b559a6fed 100644 --- a/plugins/modules/profitbricks_nic.py +++ b/plugins/modules/profitbricks_nic.py @@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: profitbricks_nic short_description: Create or Remove a NIC description: - - This module allows you to create or restore a volume snapshot. This module has a dependency on profitbricks >= 1.0.0 + - This module allows you to create or restore a volume snapshot. This module has a dependency on profitbricks >= 1.0.0. extends_documentation_fragment: - community.general.attributes attributes: @@ -39,42 +38,42 @@ options: type: str lan: description: - - The LAN to place the NIC on. You can pass a LAN that doesn't exist and it will be created. Required on create. + - The LAN to place the NIC on. You can pass a LAN that does not exist and it will be created. Required on create. type: str subscription_user: description: - - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable. + - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable. type: str required: true subscription_password: description: - - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable. + - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable. type: str required: true wait: description: - - wait for the operation to complete before returning + - Wait for the operation to complete before returning. required: false default: true type: bool wait_timeout: description: - - how long before wait gives up, in seconds + - How long before wait gives up, in seconds. type: int default: 600 state: description: - - Indicate desired state of the resource - - "The available choices are: V(present), V(absent)." + - Indicate desired state of the resource. + - 'The available choices are: V(present), V(absent).' type: str required: false default: 'present' -requirements: [ "profitbricks" ] +requirements: ["profitbricks"] author: Matt Baldwin (@baldwinSPC) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create a NIC community.general.profitbricks_nic: datacenter: Tardis One @@ -90,7 +89,7 @@ EXAMPLES = ''' name: 7341c2454f wait_timeout: 500 state: absent -''' +""" import re import uuid diff --git a/plugins/modules/profitbricks_volume.py b/plugins/modules/profitbricks_volume.py index f623da7128..48bacb2061 100644 --- a/plugins/modules/profitbricks_volume.py +++ b/plugins/modules/profitbricks_volume.py @@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: profitbricks_volume short_description: Create or destroy a volume description: - - Allows you to create or remove a volume from a ProfitBricks datacenter. This module has a dependency on profitbricks >= 1.0.0 + - Allows you to create or remove a volume from a ProfitBricks datacenter. This module has a dependency on profitbricks >= 1.0.0. extends_documentation_fragment: - community.general.attributes attributes: @@ -42,10 +41,10 @@ options: type: str required: false default: VIRTIO - choices: [ "IDE", "VIRTIO"] + choices: ["IDE", "VIRTIO"] image: description: - - The system image ID for the volume, e.g. a3eae284-a2fe-11e4-b187-5f1f641608c8. This can also be a snapshot image ID. + - The system image ID for the volume, for example V(a3eae284-a2fe-11e4-b187-5f1f641608c8). This can also be a snapshot image ID. type: str image_password: description: @@ -64,11 +63,11 @@ options: type: str required: false default: HDD - choices: [ "HDD", "SSD" ] + choices: ["HDD", "SSD"] licence_type: description: - The licence type for the volume. This is used when the image is non-standard. - - "The available choices are: V(LINUX), V(WINDOWS), V(UNKNOWN), V(OTHER)." + - 'The available choices are: V(LINUX), V(WINDOWS), V(UNKNOWN), V(OTHER).' type: str required: false default: UNKNOWN @@ -85,35 +84,35 @@ options: type: bool instance_ids: description: - - list of instance ids, currently only used when state='absent' to remove instances. + - List of instance ids, currently only used when state='absent' to remove instances. type: list elements: str default: [] subscription_user: description: - - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable. + - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable. type: str required: false subscription_password: description: - - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable. + - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable. type: str required: false wait: description: - - wait for the datacenter to be created before returning + - Wait for the datacenter to be created before returning. required: false default: true type: bool wait_timeout: description: - - how long before wait gives up, in seconds + - How long before wait gives up, in seconds. type: int default: 600 state: description: - - create or terminate datacenters - - "The available choices are: V(present), V(absent)." + - Create or terminate datacenters. + - 'The available choices are: V(present), V(absent).' type: str required: false default: 'present' @@ -122,11 +121,11 @@ options: - Server name to attach the volume to. type: str -requirements: [ "profitbricks" ] +requirements: ["profitbricks"] author: Matt Baldwin (@baldwinSPC) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Create multiple volumes community.general.profitbricks_volume: datacenter: Tardis One @@ -144,7 +143,7 @@ EXAMPLES = ''' - 'vol02' wait_timeout: 500 state: absent -''' +""" import re import time diff --git a/plugins/modules/profitbricks_volume_attachments.py b/plugins/modules/profitbricks_volume_attachments.py index 76459515ee..63ca6775ab 100644 --- a/plugins/modules/profitbricks_volume_attachments.py +++ b/plugins/modules/profitbricks_volume_attachments.py @@ -8,12 +8,11 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' ---- +DOCUMENTATION = r""" module: profitbricks_volume_attachments short_description: Attach or detach a volume description: - - Allows you to attach or detach a volume from a ProfitBricks server. This module has a dependency on profitbricks >= 1.0.0 + - Allows you to attach or detach a volume from a ProfitBricks server. This module has a dependency on profitbricks >= 1.0.0. extends_documentation_fragment: - community.general.attributes attributes: @@ -36,38 +35,38 @@ options: type: str subscription_user: description: - - The ProfitBricks username. Overrides the PB_SUBSCRIPTION_ID environment variable. + - The ProfitBricks username. Overrides the E(PB_SUBSCRIPTION_ID) environment variable. type: str required: false subscription_password: description: - - THe ProfitBricks password. Overrides the PB_PASSWORD environment variable. + - THe ProfitBricks password. Overrides the E(PB_PASSWORD) environment variable. type: str required: false wait: description: - - wait for the operation to complete before returning + - Wait for the operation to complete before returning. required: false default: true type: bool wait_timeout: description: - - how long before wait gives up, in seconds + - How long before wait gives up, in seconds. type: int default: 600 state: description: - - Indicate desired state of the resource - - "The available choices are: V(present), V(absent)." + - Indicate desired state of the resource. + - 'The available choices are: V(present), V(absent).' type: str required: false default: 'present' -requirements: [ "profitbricks" ] +requirements: ["profitbricks"] author: Matt Baldwin (@baldwinSPC) -''' +""" -EXAMPLES = ''' +EXAMPLES = r""" - name: Attach a volume community.general.profitbricks_volume_attachments: datacenter: Tardis One @@ -83,7 +82,7 @@ EXAMPLES = ''' volume: vol01 wait_timeout: 500 state: absent -''' +""" import re import time