From 5b4f41748d02cd8695b017c670b3c37a5a189828 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 8 Oct 2024 09:00:26 +1300 Subject: [PATCH] Update docs with references to man pages (#8983) * update docs with references to man pages * reformat module docs * gconftool2/_info: docs adjustments --- plugins/doc_fragments/pipx.py | 7 +- plugins/modules/ansible_galaxy_install.py | 211 +++++++++-------- plugins/modules/cpanm.py | 74 +++--- plugins/modules/gconftool2.py | 91 ++++--- plugins/modules/gconftool2_info.py | 42 ++-- plugins/modules/gio_mime.py | 70 +++--- plugins/modules/mksysb.py | 46 ++-- plugins/modules/pipx.py | 274 +++++++++++----------- plugins/modules/pipx_info.py | 77 +++--- plugins/modules/xfconf.py | 3 +- 10 files changed, 461 insertions(+), 434 deletions(-) diff --git a/plugins/doc_fragments/pipx.py b/plugins/doc_fragments/pipx.py index 112695f24f..52593f24f3 100644 --- a/plugins/doc_fragments/pipx.py +++ b/plugins/doc_fragments/pipx.py @@ -33,5 +33,10 @@ notes: - > This module will honor C(pipx) environment variables such as but not limited to E(PIPX_HOME) and E(PIPX_BIN_DIR) passed using the R(environment Ansible keyword, playbooks_environment). - - See also the C(pipx) documentation at U(https://pypa.github.io/pipx/). + +seealso: + - name: C(pipx) command manual page + description: Manual page for the command. + link: https://pipx.pypa.io/latest/docs/ + ''' diff --git a/plugins/modules/ansible_galaxy_install.py b/plugins/modules/ansible_galaxy_install.py index b0f3aeb5da..62de70bb63 100644 --- a/plugins/modules/ansible_galaxy_install.py +++ b/plugins/modules/ansible_galaxy_install.py @@ -9,23 +9,29 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = """ +--- module: ansible_galaxy_install author: - - "Alexei Znamensky (@russoz)" +- "Alexei Znamensky (@russoz)" short_description: Install Ansible roles or collections using ansible-galaxy version_added: 3.5.0 description: - - This module allows the installation of Ansible collections or roles using C(ansible-galaxy). +- This module allows the installation of Ansible collections or roles using C(ansible-galaxy). notes: - - Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0. - - > - The module will try and run using the C(C.UTF-8) locale. - If that fails, it will try C(en_US.UTF-8). - If that one also fails, the module will fail. +- Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0. +- > + The module will try and run using the C(C.UTF-8) locale. + If that fails, it will try C(en_US.UTF-8). + If that one also fails, the module will fail. +seealso: +- name: C(ansible-galaxy) command manual page + description: Manual page for the command. + link: https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html + requirements: - - ansible-core 2.11 or newer +- ansible-core 2.11 or newer extends_documentation_fragment: - - community.general.attributes +- community.general.attributes attributes: check_mode: support: none @@ -34,62 +40,63 @@ attributes: options: state: description: - - > - If O(state=present) then the collection or role will be installed. - Note that the collections and roles are not updated with this option. - - > - Currently the O(state=latest) is ignored unless O(type=collection), and it will - ensure the collection is installed and updated to the latest available version. - - Please note that O(force=true) can be used to perform upgrade regardless of O(type). + - > + If O(state=present) then the collection or role will be installed. + Note that the collections and roles are not updated with this option. + - > + Currently the O(state=latest) is ignored unless O(type=collection), and it will + ensure the collection is installed and updated to the latest available version. + - Please note that O(force=true) can be used to perform upgrade regardless of O(type). type: str - choices: [ present, latest ] + choices: [present, latest] default: present version_added: 9.1.0 type: description: - - The type of installation performed by C(ansible-galaxy). - - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections. - - "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices." + - The type of installation performed by C(ansible-galaxy). + - If O(type=both), then O(requirements_file) must be passed and it may contain both roles and collections. + - "Note however that the opposite is not true: if using a O(requirements_file), then O(type) can be any of the three choices." type: str choices: [collection, role, both] required: true name: description: - - Name of the collection or role being installed. - - > - Versions can be specified with C(ansible-galaxy) usual formats. - For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0). - - O(name) and O(requirements_file) are mutually exclusive. + - Name of the collection or role being installed. + - > + Versions can be specified with C(ansible-galaxy) usual formats. + For example, the collection V(community.docker:1.6.1) or the role V(ansistrano.deploy,3.8.0). + - O(name) and O(requirements_file) are mutually exclusive. type: str requirements_file: description: - - Path to a file containing a list of requirements to be installed. - - It works for O(type) equals to V(collection) and V(role). - - O(name) and O(requirements_file) are mutually exclusive. + - Path to a file containing a list of requirements to be installed. + - It works for O(type) equals to V(collection) and V(role). + - O(name) and O(requirements_file) are mutually exclusive. type: path dest: description: - - The path to the directory containing your collections or roles, according to the value of O(type). - - > - Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file) - contains both roles and collections and O(dest) is specified. + - The path to the directory containing your collections or roles, according to the value of O(type). + - > + Please notice that C(ansible-galaxy) will not install collections with O(type=both), when O(requirements_file) + contains both roles and collections and O(dest) is specified. type: path no_deps: description: - - Refrain from installing dependencies. + - Refrain from installing dependencies. version_added: 4.5.0 type: bool default: false force: description: - - Force overwriting existing roles and/or collections. - - It can be used for upgrading, but the module output will always report C(changed=true). - - Using O(force=true) is mandatory when downgrading. + - Force overwriting existing roles and/or collections. + - It can be used for upgrading, but the module output will always report C(changed=true). + - Using O(force=true) is mandatory when downgrading. type: bool default: false """ EXAMPLES = """ +--- - name: Install collection community.network community.general.ansible_galaxy_install: type: collection @@ -111,76 +118,76 @@ EXAMPLES = """ type: collection name: community.network:3.0.2 force: true - """ RETURN = """ - type: - description: The value of the O(type) parameter. - type: str - returned: always - name: - description: The value of the O(name) parameter. - type: str - returned: always - dest: - description: The value of the O(dest) parameter. - type: str - returned: always - requirements_file: - description: The value of the O(requirements_file) parameter. - type: str - returned: always - force: - description: The value of the O(force) parameter. - type: bool - returned: always - installed_roles: - description: - - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path. - - If O(name) is specified, returns that role name and the version installed per path. - type: dict - returned: always when installing roles - contains: - "": - description: Roles and versions for that path. - type: dict - sample: - /home/user42/.ansible/roles: - ansistrano.deploy: 3.9.0 - baztian.xfce: v0.0.3 - /custom/ansible/roles: - ansistrano.deploy: 3.8.0 - installed_collections: - description: - - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path. - - If O(name) is specified, returns that collection name and the version installed per path. - type: dict - returned: always when installing collections - contains: - "": - description: Collections and versions for that path - type: dict - sample: - /home/az/.ansible/collections/ansible_collections: - community.docker: 1.6.0 - community.general: 3.0.2 - /custom/ansible/ansible_collections: - community.general: 3.1.0 - new_collections: - description: New collections installed by this module. - returned: success - type: dict - sample: - community.general: 3.1.0 - community.docker: 1.6.1 - new_roles: - description: New roles installed by this module. - returned: success - type: dict - sample: - ansistrano.deploy: 3.8.0 +--- +type: + description: The value of the O(type) parameter. + type: str + returned: always +name: + description: The value of the O(name) parameter. + type: str + returned: always +dest: + description: The value of the O(dest) parameter. + type: str + returned: always +requirements_file: + description: The value of the O(requirements_file) parameter. + type: str + returned: always +force: + description: The value of the O(force) parameter. + type: bool + returned: always +installed_roles: + description: + - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path. + - If O(name) is specified, returns that role name and the version installed per path. + type: dict + returned: always when installing roles + contains: + "": + description: Roles and versions for that path. + type: dict + sample: + /home/user42/.ansible/roles: + ansistrano.deploy: 3.9.0 baztian.xfce: v0.0.3 + /custom/ansible/roles: + ansistrano.deploy: 3.8.0 +installed_collections: + description: + - If O(requirements_file) is specified instead, returns dictionary with all the collections installed per path. + - If O(name) is specified, returns that collection name and the version installed per path. + type: dict + returned: always when installing collections + contains: + "": + description: Collections and versions for that path + type: dict + sample: + /home/az/.ansible/collections/ansible_collections: + community.docker: 1.6.0 + community.general: 3.0.2 + /custom/ansible/ansible_collections: + community.general: 3.1.0 +new_collections: + description: New collections installed by this module. + returned: success + type: dict + sample: + community.general: 3.1.0 + community.docker: 1.6.1 +new_roles: + description: New roles installed by this module. + returned: success + type: dict + sample: + ansistrano.deploy: 3.8.0 + baztian.xfce: v0.0.3 """ import re diff --git a/plugins/modules/cpanm.py b/plugins/modules/cpanm.py index 3beae895dc..25489170dd 100644 --- a/plugins/modules/cpanm.py +++ b/plugins/modules/cpanm.py @@ -10,14 +10,14 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = """ --- module: cpanm short_description: Manages Perl library dependencies description: - - Manage Perl library dependencies using cpanminus. +- Manage Perl library dependencies using cpanminus. extends_documentation_fragment: - - community.general.attributes +- community.general.attributes attributes: check_mode: support: none @@ -27,76 +27,82 @@ options: name: type: str description: - - The Perl library to install. Valid values change according to the O(mode), see notes for more details. - - Note that for installing from a local path the parameter O(from_path) should be used. + - The Perl library to install. Valid values change according to the O(mode), see notes for more details. + - Note that for installing from a local path the parameter O(from_path) should be used. aliases: [pkg] from_path: type: path description: - - The local directory or C(tar.gz) file to install from. + - The local directory or C(tar.gz) file to install from. notest: description: - - Do not run unit tests. + - Do not run unit tests. type: bool default: false locallib: description: - - Specify the install base to install modules. + - Specify the install base to install modules. type: path mirror: description: - - Specifies the base URL for the CPAN mirror to use. + - Specifies the base URL for the CPAN mirror to use. type: str mirror_only: description: - - Use the mirror's index file instead of the CPAN Meta DB. + - Use the mirror's index file instead of the CPAN Meta DB. type: bool default: false installdeps: description: - - Only install dependencies. + - Only install dependencies. type: bool default: false version: description: - - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted. + - Version specification for the perl module. When O(mode) is V(new), C(cpanm) version operators are accepted. type: str executable: description: - - Override the path to the cpanm executable. + - Override the path to the cpanm executable. type: path mode: description: - - Controls the module behavior. See notes below for more details. - - The default changed from V(compatibility) to V(new) in community.general 9.0.0. + - Controls the module behavior. See notes below for more details. + - The default changed from V(compatibility) to V(new) in community.general 9.0.0. type: str choices: [compatibility, new] default: new version_added: 3.0.0 name_check: description: - - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified). + - When O(mode=new), this parameter can be used to check if there is a module O(name) installed (at O(version), when specified). type: str version_added: 3.0.0 notes: - - Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host. - - "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)." - - > - O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. - This was the default mode before community.general 9.0.0. - O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version) - when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL. - C(cpanm) version specifiers do not work in this mode. - - > - O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file, - a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized. - This is the default mode from community.general 9.0.0 onwards. -author: - - "Franck Cuny (@fcuny)" - - "Alexei Znamensky (@russoz)" -''' +- Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host. +- "This module now comes with a choice of execution O(mode): V(compatibility) or V(new)." +- > + O(mode=compatibility): When using V(compatibility) mode, the module will keep backward compatibility. + This was the default mode before community.general 9.0.0. + O(name) must be either a module name or a distribution file. If the perl module given by O(name) is installed (at the exact O(version) + when specified), then nothing happens. Otherwise, it will be installed using the C(cpanm) executable. O(name) cannot be an URL, or a git URL. + C(cpanm) version specifiers do not work in this mode. +- > + O(mode=new): When using V(new) mode, the module will behave differently. The O(name) parameter may refer to a module name, a distribution file, + a HTTP URL or a git repository URL as described in C(cpanminus) documentation. C(cpanm) version specifiers are recognized. + This is the default mode from community.general 9.0.0 onwards. -EXAMPLES = ''' +seealso: +- name: C(cpanm) command manual page + description: Manual page for the command. + link: https://metacpan.org/dist/App-cpanminus/view/bin/cpanm +author: +- "Franck Cuny (@fcuny)" +- "Alexei Znamensky (@russoz)" +""" + +EXAMPLES = """ +--- - name: Install Dancer perl package community.general.cpanm: name: Dancer @@ -134,7 +140,7 @@ EXAMPLES = ''' community.general.cpanm: name: Dancer version: '1.0' -''' +""" import os diff --git a/plugins/modules/gconftool2.py b/plugins/modules/gconftool2.py index deae8a2f16..7cf9a92c44 100644 --- a/plugins/modules/gconftool2.py +++ b/plugins/modules/gconftool2.py @@ -9,16 +9,21 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = """ +--- 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 via 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 + extends_documentation_fragment: - - community.general.attributes +- community.general.attributes attributes: check_mode: support: full @@ -28,42 +33,36 @@ options: key: type: str description: - - A GConf preference key is an element in the GConf repository - that corresponds to an application preference. See man gconftool-2(1). + - 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). See man gconftool-2(1). + - 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). See man gconftool-2(1). - choices: [ bool, float, int, string ] + - 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. required: true - choices: [ absent, present ] + choices: [absent, present] config_source: type: str description: - Specify a configuration source to use rather than the default path. - See man gconftool-2(1). direct: description: - - Access the config database directly, bypassing server. If O(direct) is - specified then the O(config_source) must be specified as well. - See man gconftool-2(1). + - 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 = """ +--- - name: Change the widget font to "Serif 12" community.general.gconftool2: key: "/desktop/gnome/interface/font_name" @@ -71,33 +70,33 @@ EXAMPLES = """ value: "Serif 12" """ -RETURN = ''' - key: - description: The key specified in the module parameters. - returned: success - type: str - sample: /desktop/gnome/interface/font_name - value_type: - description: The type of the value that was changed. - returned: success - type: str - 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. - 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. - returned: success - type: str - sample: "Serif 12" -... -''' +RETURN = """ +--- +key: + description: The key specified in the module parameters. + returned: success + type: str + sample: /desktop/gnome/interface/font_name +value_type: + description: The type of the value that was changed. + returned: success + type: str + 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. + 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. + returned: success + type: str + sample: "Serif 12" +""" from ansible_collections.community.general.plugins.module_utils.module_helper import StateModuleHelper from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner diff --git a/plugins/modules/gconftool2_info.py b/plugins/modules/gconftool2_info.py index f66e2da8f7..ebe2121ad1 100644 --- a/plugins/modules/gconftool2_info.py +++ b/plugins/modules/gconftool2_info.py @@ -7,46 +7,50 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = """ +--- 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. type: str required: true -notes: - - See man gconftool-2(1) for more details. seealso: - - 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 = """ +--- - name: Get value for a certain key in the database. community.general.gconftool2_info: key: /desktop/gnome/background/picture_filename register: result """ -RETURN = ''' - value: - description: - - The value of the property. - returned: success - type: str - sample: Monospace 10 -''' +RETURN = """ +--- +value: + description: + - The value of the property. + returned: success + type: str + sample: Monospace 10 +""" from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner diff --git a/plugins/modules/gio_mime.py b/plugins/modules/gio_mime.py index bb1ef6ebe3..20ccb22329 100644 --- a/plugins/modules/gio_mime.py +++ b/plugins/modules/gio_mime.py @@ -7,16 +7,17 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = """ +--- 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 th Gnome GIO API. extends_documentation_fragment: - - community.general.attributes +- community.general.attributes attributes: check_mode: support: full @@ -25,24 +26,28 @@ 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: 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 = """ +--- - name: Set chrome as the default handler for https community.general.gio_mime: mime_type: x-scheme-handler/https @@ -50,26 +55,27 @@ EXAMPLES = """ register: result """ -RETURN = ''' - handler: - description: - - The handler set as default. - returned: success - type: str - sample: google-chrome.desktop - stdout: - description: - - 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. - returned: failure - type: str - sample: 'gio: Failed to load info for handler "never-existed.desktop"' -''' +RETURN = """ +--- +handler: + description: + - The handler set as default. + returned: success + type: str + sample: google-chrome.desktop +stdout: + description: + - 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. + returned: failure + type: str + sample: 'gio: Failed to load info for handler "never-existed.desktop"' +""" from ansible_collections.community.general.plugins.module_utils.module_helper import ModuleHelper from ansible_collections.community.general.plugins.module_utils.gio_mime import gio_mime_runner, gio_mime_get diff --git a/plugins/modules/mksysb.py b/plugins/modules/mksysb.py index 1280f04d59..d1f49ca82e 100644 --- a/plugins/modules/mksysb.py +++ b/plugins/modules/mksysb.py @@ -10,15 +10,20 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = """ --- author: Kairo Araujo (@kairoaraujo) module: mksysb short_description: Generates AIX mksysb rootvg backups description: - - This module manages a basic AIX mksysb (image) of rootvg. +- This module manages a basic AIX mksysb (image) of rootvg. +seealso: +- name: C(mksysb) command manual page + description: Manual page for the command. + link: https://www.ibm.com/docs/en/aix/7.3?topic=m-mksysb-command + extends_documentation_fragment: - - community.general.attributes +- community.general.attributes attributes: check_mode: support: full @@ -27,72 +32,73 @@ attributes: options: backup_crypt_files: description: - - Backup encrypted files. + - Backup encrypted files. type: bool default: true backup_dmapi_fs: description: - - Back up DMAPI filesystem files. + - Back up DMAPI filesystem files. type: bool default: true create_map_files: description: - - Creates a new MAP files. + - Creates a new MAP files. type: bool default: false exclude_files: description: - - Excludes files using C(/etc/rootvg.exclude). + - Excludes files using C(/etc/rootvg.exclude). type: bool default: false exclude_wpar_files: description: - - Excludes WPAR files. + - Excludes WPAR files. type: bool default: false extended_attrs: description: - - Backup extended attributes. + - Backup extended attributes. type: bool default: true name: type: str description: - - Backup name + - Backup name required: true new_image_data: description: - - Creates a new file data. + - Creates a new file data. type: bool default: true software_packing: description: - - Exclude files from packing option listed in - C(/etc/exclude_packing.rootvg). + - Exclude files from packing option listed in C(/etc/exclude_packing.rootvg). type: bool default: false storage_path: type: str description: - - Storage path where the mksysb will stored. + - Storage path where the mksysb will stored. required: true use_snapshot: description: - - Creates backup using snapshots. + - Creates backup using snapshots. type: bool default: false -''' +""" -EXAMPLES = ''' +EXAMPLES = """ +--- - name: Running a backup image mksysb community.general.mksysb: name: myserver storage_path: /repository/images exclude_files: true exclude_wpar_files: true -''' +""" -RETURN = ''' +RETURN = """ +--- changed: description: Return changed for mksysb actions as true or false. returned: always @@ -101,7 +107,7 @@ msg: description: Return message regarding the action. returned: always type: str -''' +""" import os diff --git a/plugins/modules/pipx.py b/plugins/modules/pipx.py index f9ad13980d..c317ae8da8 100644 --- a/plugins/modules/pipx.py +++ b/plugins/modules/pipx.py @@ -9,150 +9,150 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = """ --- 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 - diff_mode: - support: full + check_mode: + support: full + diff_mode: + support: full 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 - 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. - 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. - 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. - install_apps: - description: - - 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). - type: bool - default: false - inject_packages: - description: - - 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). - 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. - 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). - 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). - 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). - type: bool - default: false - version_added: 6.6.0 - editable: - description: - - 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). - 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." - 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). - type: path - version_added: 9.4.0 + 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 + 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. + 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. + 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. + install_apps: + description: + - 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). + type: bool + default: false + inject_packages: + description: + - 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). + 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. + 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). + 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). + 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). + type: bool + default: false + version_added: 6.6.0 + editable: + description: + - 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). + 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." + 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). + 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 = """ +--- - name: Install tox community.general.pipx: name: tox @@ -181,14 +181,14 @@ 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 }}" -''' +""" import json diff --git a/plugins/modules/pipx_info.py b/plugins/modules/pipx_info.py index 0e0cc0fe14..65c0ba552e 100644 --- a/plugins/modules/pipx_info.py +++ b/plugins/modules/pipx_info.py @@ -9,45 +9,46 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' +DOCUMENTATION = """ --- 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). - type: str - include_deps: - description: - - Include dependent packages in the output. - type: bool - default: false - include_injected: - description: - - 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). - type: bool - default: false - global: - version_added: 9.3.0 + name: + description: + - Name of an application installed with C(pipx). + type: str + include_deps: + description: + - Include dependent packages in the output. + type: bool + default: false + include_injected: + description: + - 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). + type: bool + default: false + global: + version_added: 9.3.0 author: - - "Alexei Znamensky (@russoz)" -''' +- "Alexei Znamensky (@russoz)" +""" -EXAMPLES = ''' +EXAMPLES = """ +--- - name: retrieve all installed applications community.general.pipx_info: {} @@ -65,9 +66,10 @@ EXAMPLES = ''' community.general.pipx_info: name: ansible-lint include_deps: true -''' +""" -RETURN = ''' +RETURN = """ +--- application: description: The list of installed applications returned: success @@ -107,15 +109,8 @@ cmd: returned: success type: list elements: str - sample: [ - "/usr/bin/python3.10", - "-m", - "pipx", - "list", - "--include-injected", - "--json" - ] -''' + sample: ["/usr/bin/python3.10", "-m", "pipx", "list", "--include-injected", "--json"] +""" import json diff --git a/plugins/modules/xfconf.py b/plugins/modules/xfconf.py index 2e1e67ff32..8bb0abc273 100644 --- a/plugins/modules/xfconf.py +++ b/plugins/modules/xfconf.py @@ -16,8 +16,7 @@ author: - "Alexei Znamensky (@russoz)" short_description: Edit XFCE4 Configurations description: -- This module allows for the manipulation of Xfce 4 Configuration with the help of xfconf-query. Please see the xfconf-query(1) man page for more - details. +- This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query). seealso: - name: xfconf-query(1) man page description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.