a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[PR #8983/5b4f4174 backport][stable-9] Update docs with references to man pages (#8994) 

Update docs with references to man pages (#8983)

* update docs with references to man pages

* reformat module docs

* gconftool2/_info: docs adjustments

(cherry picked from commit 5b4f41748d)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
pull/9004/head
patchback[bot] 2024-10-07 22:19:29 +02:00 committed by GitHub
parent 2766898ea8
commit bc4fda8b14
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 461 additions and 434 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
plugins/doc_fragments/pipx.py
View File

@ -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) 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). 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/
''' '''

211
plugins/modules/ansible_galaxy_install.py
View File

@ -9,23 +9,29 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = """
---
module: ansible_galaxy_install module: ansible_galaxy_install
author: author:
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
short_description: Install Ansible roles or collections using ansible-galaxy short_description: Install Ansible roles or collections using ansible-galaxy
version_added: 3.5.0 version_added: 3.5.0
description: 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: notes:
- Support for B(Ansible 2.9/2.10) was removed in community.general 8.0.0. - 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. 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 fails, it will try C(en_US.UTF-8).
If that one also fails, the module will fail. 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: requirements:
- ansible-core 2.11 or newer - ansible-core 2.11 or newer
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
@ -34,62 +40,63 @@ attributes:
options: options:
state: state:
description: description:
- > - >
If O(state=present) then the collection or role will be installed. If O(state=present) then the collection or role will be installed.
Note that the collections and roles are not updated with this option. 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 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. 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). - Please note that O(force=true) can be used to perform upgrade regardless of O(type).
type: str type: str
choices: [ present, latest ] choices: [present, latest]
default: present default: present
version_added: 9.1.0 version_added: 9.1.0
type: type:
description: description:
- The type of installation performed by C(ansible-galaxy). - 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. - 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." - "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 type: str
choices: [collection, role, both] choices: [collection, role, both]
required: true required: true
name: name:
description: description:
- Name of the collection or role being installed. - Name of the collection or role being installed.
- > - >
Versions can be specified with C(ansible-galaxy) usual formats. 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). 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. - O(name) and O(requirements_file) are mutually exclusive.
type: str type: str
requirements_file: requirements_file:
description: description:
- Path to a file containing a list of requirements to be installed. - Path to a file containing a list of requirements to be installed.
- It works for O(type) equals to V(collection) and V(role). - It works for O(type) equals to V(collection) and V(role).
- O(name) and O(requirements_file) are mutually exclusive. - O(name) and O(requirements_file) are mutually exclusive.
type: path type: path
dest: dest:
description: description:
- The path to the directory containing your collections or roles, according to the value of O(type). - 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) 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. contains both roles and collections and O(dest) is specified.
type: path type: path
no_deps: no_deps:
description: description:
- Refrain from installing dependencies. - Refrain from installing dependencies.
version_added: 4.5.0 version_added: 4.5.0
type: bool type: bool
default: false default: false
force: force:
description: description:
- Force overwriting existing roles and/or collections. - Force overwriting existing roles and/or collections.
- It can be used for upgrading, but the module output will always report C(changed=true). - It can be used for upgrading, but the module output will always report C(changed=true).
- Using O(force=true) is mandatory when downgrading. - Using O(force=true) is mandatory when downgrading.
type: bool type: bool
default: false default: false
""" """
EXAMPLES = """ EXAMPLES = """
---
- name: Install collection community.network - name: Install collection community.network
community.general.ansible_galaxy_install: community.general.ansible_galaxy_install:
type: collection type: collection
@ -111,76 +118,76 @@ EXAMPLES = """
type: collection type: collection
name: community.network:3.0.2 name: community.network:3.0.2
force: true force: true
""" """
RETURN = """ RETURN = """
type: ---
description: The value of the O(type) parameter. type:
type: str description: The value of the O(type) parameter.
returned: always type: str
name: returned: always
description: The value of the O(name) parameter. name:
type: str description: The value of the O(name) parameter.
returned: always type: str
dest: returned: always
description: The value of the O(dest) parameter. dest:
type: str description: The value of the O(dest) parameter.
returned: always type: str
requirements_file: returned: always
description: The value of the O(requirements_file) parameter. requirements_file:
type: str description: The value of the O(requirements_file) parameter.
returned: always type: str
force: returned: always
description: The value of the O(force) parameter. force:
type: bool description: The value of the O(force) parameter.
returned: always type: bool
installed_roles: returned: always
description: installed_roles:
- If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path. description:
- If O(name) is specified, returns that role name and the version installed per path. - If O(requirements_file) is specified instead, returns dictionary with all the roles installed per path.
type: dict - If O(name) is specified, returns that role name and the version installed per path.
returned: always when installing roles type: dict
contains: returned: always when installing roles
"<path>": contains:
description: Roles and versions for that path. "<path>":
type: dict description: Roles and versions for that path.
sample: type: dict
/home/user42/.ansible/roles: sample:
ansistrano.deploy: 3.9.0 /home/user42/.ansible/roles:
baztian.xfce: v0.0.3 ansistrano.deploy: 3.9.0
/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:
"<path>":
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 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:
"<path>":
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 import re

74
plugins/modules/cpanm.py
View File

@ -10,14 +10,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = """
--- ---
module: cpanm module: cpanm
short_description: Manages Perl library dependencies short_description: Manages Perl library dependencies
description: description:
- Manage Perl library dependencies using cpanminus. - Manage Perl library dependencies using cpanminus.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
@ -27,76 +27,82 @@ options:
name: name:
type: str type: str
description: description:
- The Perl library to install. Valid values change according to the O(mode), see notes for more details. - 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. - Note that for installing from a local path the parameter O(from_path) should be used.
aliases: [pkg] aliases: [pkg]
from_path: from_path:
type: path type: path
description: description:
- The local directory or C(tar.gz) file to install from. - The local directory or C(tar.gz) file to install from.
notest: notest:
description: description:
- Do not run unit tests. - Do not run unit tests.
type: bool type: bool
default: false default: false
locallib: locallib:
description: description:
- Specify the install base to install modules. - Specify the install base to install modules.
type: path type: path
mirror: mirror:
description: description:
- Specifies the base URL for the CPAN mirror to use. - Specifies the base URL for the CPAN mirror to use.
type: str type: str
mirror_only: mirror_only:
description: 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 type: bool
default: false default: false
installdeps: installdeps:
description: description:
- Only install dependencies. - Only install dependencies.
type: bool type: bool
default: false default: false
version: version:
description: 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 type: str
executable: executable:
description: description:
- Override the path to the cpanm executable. - Override the path to the cpanm executable.
type: path type: path
mode: mode:
description: description:
- Controls the module behavior. See notes below for more details. - 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. - The default changed from V(compatibility) to V(new) in community.general 9.0.0.
type: str type: str
choices: [compatibility, new] choices: [compatibility, new]
default: new default: new
version_added: 3.0.0 version_added: 3.0.0
name_check: name_check:
description: 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 type: str
version_added: 3.0.0 version_added: 3.0.0
notes: notes:
- Please note that U(http://search.cpan.org/dist/App-cpanminus/bin/cpanm, cpanm) must be installed on the remote host. - 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)." - "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. 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. 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) 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. 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. 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, 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. 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. This is the default mode from community.general 9.0.0 onwards.
author:
- "Franck Cuny (@fcuny)"
- "Alexei Znamensky (@russoz)"
'''
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 - name: Install Dancer perl package
community.general.cpanm: community.general.cpanm:
name: Dancer name: Dancer
@ -134,7 +140,7 @@ EXAMPLES = '''
community.general.cpanm: community.general.cpanm:
name: Dancer name: Dancer
version: '1.0' version: '1.0'
''' """
import os import os

91
plugins/modules/gconftool2.py
View File

@ -9,16 +9,21 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = """
---
module: gconftool2 module: gconftool2
author: author:
- Kenneth D. Evensen (@kevensen) - Kenneth D. Evensen (@kevensen)
short_description: Edit GNOME Configurations short_description: Edit GNOME Configurations
description: description:
- This module allows for the manipulation of GNOME 2 Configuration via - This module allows for the manipulation of GNOME 2 Configuration via gconftool-2. Please see the gconftool-2(1) man pages for more details.
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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -28,42 +33,36 @@ options:
key: key:
type: str type: str
description: description:
- A GConf preference key is an element in the GConf repository - A GConf preference key is an element in the GConf repository that corresponds to an application preference.
that corresponds to an application preference. See man gconftool-2(1).
required: true required: true
value: value:
type: str type: str
description: description:
- Preference keys typically have simple values such as strings, - Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is ignored unless O(state=present).
integers, or lists of strings and integers.
This is ignored unless O(state=present). See man gconftool-2(1).
value_type: value_type:
type: str type: str
description: description:
- The type of value being set. - The type of value being set. This is ignored unless O(state=present).
This is ignored unless O(state=present). See man gconftool-2(1). choices: [bool, float, int, string]
choices: [ bool, float, int, string ]
state: state:
type: str type: str
description: description:
- The action to take upon the key/value. - The action to take upon the key/value.
required: true required: true
choices: [ absent, present ] choices: [absent, present]
config_source: config_source:
type: str type: str
description: description:
- Specify a configuration source to use rather than the default path. - Specify a configuration source to use rather than the default path.
See man gconftool-2(1).
direct: direct:
description: description:
- Access the config database directly, bypassing server. If O(direct) is - Access the config database directly, bypassing server. If O(direct) is specified then the O(config_source) must be specified as well.
specified then the O(config_source) must be specified as well.
See man gconftool-2(1).
type: bool type: bool
default: false default: false
''' """
EXAMPLES = """ EXAMPLES = """
---
- name: Change the widget font to "Serif 12" - name: Change the widget font to "Serif 12"
community.general.gconftool2: community.general.gconftool2:
key: "/desktop/gnome/interface/font_name" key: "/desktop/gnome/interface/font_name"
@ -71,33 +70,33 @@ EXAMPLES = """
value: "Serif 12" value: "Serif 12"
""" """
RETURN = ''' RETURN = """
key: ---
description: The key specified in the module parameters. key:
returned: success description: The key specified in the module parameters.
type: str returned: success
sample: /desktop/gnome/interface/font_name type: str
value_type: sample: /desktop/gnome/interface/font_name
description: The type of the value that was changed. value_type:
returned: success description: The type of the value that was changed.
type: str returned: success
sample: string type: str
value: sample: string
description: value:
- The value of the preference key after executing the module or V(null) if key is removed. description:
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that. - The value of the preference key after executing the module or V(null) if key is removed.
returned: success - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
type: str returned: success
sample: "Serif 12" type: str
previous_value: sample: "Serif 12"
description: previous_value:
- The value of the preference key before executing the module. description:
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that. - The value of the preference key before executing the module.
returned: success - From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
type: str returned: success
sample: "Serif 12" 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.module_helper import StateModuleHelper
from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner

42
plugins/modules/gconftool2_info.py
View File

@ -7,46 +7,50 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = """
---
module: gconftool2_info module: gconftool2_info
author: author:
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
short_description: Retrieve GConf configurations short_description: Retrieve GConf configurations
version_added: 5.1.0 version_added: 5.1.0
description: 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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.attributes.info_module - community.general.attributes.info_module
options: options:
key: key:
description: description:
- The key name for an element in the GConf database. - The key name for an element in the GConf database.
type: str type: str
required: true required: true
notes:
- See man gconftool-2(1) for more details.
seealso: seealso:
- name: gconf repository (archived) - name: C(gconftool-2) command manual page
description: Git repository for the project. It is an archived project, so the repository is read-only. description: Manual page for the command.
link: https://gitlab.gnome.org/Archive/gconf link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
''' - name: gconf repository (archived)
description: Git repository for the project. It is an archived project, so the repository is read-only.
link: https://gitlab.gnome.org/Archive/gconf
"""
EXAMPLES = """ EXAMPLES = """
---
- name: Get value for a certain key in the database. - name: Get value for a certain key in the database.
community.general.gconftool2_info: community.general.gconftool2_info:
key: /desktop/gnome/background/picture_filename key: /desktop/gnome/background/picture_filename
register: result register: result
""" """
RETURN = ''' RETURN = """
value: ---
description: value:
- The value of the property. description:
returned: success - The value of the property.
type: str returned: success
sample: Monospace 10 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.module_helper import ModuleHelper
from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner from ansible_collections.community.general.plugins.module_utils.gconftool2 import gconftool2_runner

70
plugins/modules/gio_mime.py
View File

@ -7,16 +7,17 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = """
---
module: gio_mime module: gio_mime
author: author:
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
short_description: Set default handler for MIME type, for applications using Gnome GIO short_description: Set default handler for MIME type, for applications using Gnome GIO
version_added: 7.5.0 version_added: 7.5.0
description: 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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -25,24 +26,28 @@ attributes:
options: options:
mime_type: mime_type:
description: description:
- MIME type for which a default handler will be set. - MIME type for which a default handler will be set.
type: str type: str
required: true required: true
handler: handler:
description: description:
- Default handler will be set for the MIME type. - Default handler will be set for the MIME type.
type: str type: str
required: true required: true
notes: notes:
- This module is a thin wrapper around the C(gio mime) command (and subcommand). - This module is a thin wrapper around the C(gio mime) command (and subcommand).
- See man gio(1) for more details. - See man gio(1) for more details.
seealso: seealso:
- name: GIO Documentation - name: C(gio) command manual page
description: Reference documentation for the GIO API.. description: Manual page for the command.
link: https://docs.gtk.org/gio/ link: https://man.archlinux.org/man/gio.1
''' - name: GIO Documentation
description: Reference documentation for the GIO API..
link: https://docs.gtk.org/gio/
"""
EXAMPLES = """ EXAMPLES = """
---
- name: Set chrome as the default handler for https - name: Set chrome as the default handler for https
community.general.gio_mime: community.general.gio_mime:
mime_type: x-scheme-handler/https mime_type: x-scheme-handler/https
@ -50,26 +55,27 @@ EXAMPLES = """
register: result register: result
""" """
RETURN = ''' RETURN = """
handler: ---
description: handler:
- The handler set as default. description:
returned: success - The handler set as default.
type: str returned: success
sample: google-chrome.desktop type: str
stdout: sample: google-chrome.desktop
description: stdout:
- The output of the C(gio) command. description:
returned: success - The output of the C(gio) command.
type: str returned: success
sample: Set google-chrome.desktop as the default for x-scheme-handler/https type: str
stderr: sample: Set google-chrome.desktop as the default for x-scheme-handler/https
description: stderr:
- The error output of the C(gio) command. description:
returned: failure - The error output of the C(gio) command.
type: str returned: failure
sample: 'gio: Failed to load info for handler "never-existed.desktop"' 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.module_helper import ModuleHelper
from ansible_collections.community.general.plugins.module_utils.gio_mime import gio_mime_runner, gio_mime_get from ansible_collections.community.general.plugins.module_utils.gio_mime import gio_mime_runner, gio_mime_get

46
plugins/modules/mksysb.py
View File

@ -10,15 +10,20 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = """
--- ---
author: Kairo Araujo (@kairoaraujo) author: Kairo Araujo (@kairoaraujo)
module: mksysb module: mksysb
short_description: Generates AIX mksysb rootvg backups short_description: Generates AIX mksysb rootvg backups
description: 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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -27,72 +32,73 @@ attributes:
options: options:
backup_crypt_files: backup_crypt_files:
description: description:
- Backup encrypted files. - Backup encrypted files.
type: bool type: bool
default: true default: true
backup_dmapi_fs: backup_dmapi_fs:
description: description:
- Back up DMAPI filesystem files. - Back up DMAPI filesystem files.
type: bool type: bool
default: true default: true
create_map_files: create_map_files:
description: description:
- Creates a new MAP files. - Creates a new MAP files.
type: bool type: bool
default: false default: false
exclude_files: exclude_files:
description: description:
- Excludes files using C(/etc/rootvg.exclude). - Excludes files using C(/etc/rootvg.exclude).
type: bool type: bool
default: false default: false
exclude_wpar_files: exclude_wpar_files:
description: description:
- Excludes WPAR files. - Excludes WPAR files.
type: bool type: bool
default: false default: false
extended_attrs: extended_attrs:
description: description:
- Backup extended attributes. - Backup extended attributes.
type: bool type: bool
default: true default: true
name: name:
type: str type: str
description: description:
- Backup name - Backup name
required: true required: true
new_image_data: new_image_data:
description: description:
- Creates a new file data. - Creates a new file data.
type: bool type: bool
default: true default: true
software_packing: software_packing:
description: description:
- Exclude files from packing option listed in - Exclude files from packing option listed in C(/etc/exclude_packing.rootvg).
C(/etc/exclude_packing.rootvg).
type: bool type: bool
default: false default: false
storage_path: storage_path:
type: str type: str
description: description:
- Storage path where the mksysb will stored. - Storage path where the mksysb will stored.
required: true required: true
use_snapshot: use_snapshot:
description: description:
- Creates backup using snapshots. - Creates backup using snapshots.
type: bool type: bool
default: false default: false
''' """
EXAMPLES = ''' EXAMPLES = """
---
- name: Running a backup image mksysb - name: Running a backup image mksysb
community.general.mksysb: community.general.mksysb:
name: myserver name: myserver
storage_path: /repository/images storage_path: /repository/images
exclude_files: true exclude_files: true
exclude_wpar_files: true exclude_wpar_files: true
''' """
RETURN = ''' RETURN = """
---
changed: changed:
description: Return changed for mksysb actions as true or false. description: Return changed for mksysb actions as true or false.
returned: always returned: always
@ -101,7 +107,7 @@ msg:
description: Return message regarding the action. description: Return message regarding the action.
returned: always returned: always
type: str type: str
''' """
import os import os

274
plugins/modules/pipx.py
View File

@ -9,150 +9,150 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = """
--- ---
module: pipx module: pipx
short_description: Manages applications installed with pipx short_description: Manages applications installed with pipx
version_added: 3.8.0 version_added: 3.8.0
description: description:
- Manage Python applications installed in isolated virtualenvs using pipx. - Manage Python applications installed in isolated virtualenvs using pipx.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.pipx - community.general.pipx
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: full support: full
options: options:
state: state:
type: str type: str
choices: choices:
- present - present
- absent - absent
- install - install
- install_all - install_all
- uninstall - uninstall
- uninstall_all - uninstall_all
- inject - inject
- uninject - uninject
- upgrade - upgrade
- upgrade_shared - upgrade_shared
- upgrade_all - upgrade_all
- reinstall - reinstall
- reinstall_all - reinstall_all
- latest - latest
- pin - pin
- unpin - unpin
default: install default: install
description: description:
- Desired state for the application. - Desired state for the application.
- The states V(present) and V(absent) are aliases to V(install) and V(uninstall), respectively. - 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). - 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
It was added in community.general 5.5.0. 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), - 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
make sure to have a compatible version when using this option. These states have been added in community.general 9.4.0. compatible version when using this option. These states have been added in community.general 9.4.0.
name: name:
type: str type: str
description: description:
- The name of the application. In C(pipx) documentation it is also referred to as - The name of the application. In C(pipx) documentation it is also referred to as the name of the virtual environment where the application
the name of the virtual environment where the application will be installed. will be installed.
- If O(name) is a simple package name without version specifiers, - If O(name) is a simple package name without version specifiers, then that name is used as the Python package name to be installed.
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.
- Use O(source) for passing package specifications or installing from URLs or directories. source:
source: type: str
type: str description:
description: - Source for the package. This option is used when O(state=install) or O(state=latest), and it is ignored with other states.
- 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.
- 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).
- 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.
- O(name) is still required when using O(source) to establish the application name without fetching the package from a remote source. install_apps:
install_apps: description:
description: - Add apps from the injected packages.
- Add apps from the injected packages. - Only used when O(state=inject).
- Only used when O(state=inject). type: bool
type: bool default: false
default: false version_added: 6.5.0
version_added: 6.5.0 install_deps:
install_deps: description:
description: - Include applications of dependent packages.
- Include applications of dependent packages. - Only used when O(state=install), O(state=latest), or O(state=inject).
- Only used when O(state=install), O(state=latest), or O(state=inject). type: bool
type: bool default: false
default: false inject_packages:
inject_packages: description:
description: - Packages to be injected into an existing virtual environment.
- Packages to be injected into an existing virtual environment. - Only used when O(state=inject).
- Only used when O(state=inject). type: list
type: list elements: str
elements: str force:
force: description:
description: - Force modification of the application's virtual environment. See C(pipx) for details.
- 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).
- Only used when O(state=install), O(state=upgrade), O(state=upgrade_all), O(state=latest), or O(state=inject). type: bool
type: bool default: false
default: false include_injected:
include_injected: description:
description: - Upgrade the injected packages along with the application.
- Upgrade the injected packages along with the application. - Only used when O(state=upgrade), O(state=upgrade_all), or O(state=latest).
- 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.
- This is used with O(state=upgrade) and O(state=latest) since community.general 6.6.0. type: bool
type: bool default: false
default: false index_url:
index_url: description:
description: - Base URL of Python Package Index.
- Base URL of Python Package Index. - Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject).
- Only used when O(state=install), O(state=upgrade), O(state=latest), or O(state=inject). type: str
type: str python:
python: description:
description: - Python version to be used when creating the application virtual environment. Must be 3.6+.
- 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).
- Only used when O(state=install), O(state=latest), O(state=reinstall), or O(state=reinstall_all). type: str
type: str system_site_packages:
system_site_packages: description:
description: - Give application virtual environment access to the system site-packages directory.
- Give application virtual environment access to the system site-packages directory. - Only used when O(state=install) or O(state=latest).
- Only used when O(state=install) or O(state=latest). type: bool
type: bool default: false
default: false version_added: 6.6.0
version_added: 6.6.0 editable:
editable: description:
description: - Install the project in editable mode.
- Install the project in editable mode. type: bool
type: bool default: false
default: false version_added: 4.6.0
version_added: 4.6.0 pip_args:
pip_args: description:
description: - Arbitrary arguments to pass directly to C(pip).
- Arbitrary arguments to pass directly to C(pip). type: str
type: str version_added: 4.6.0
version_added: 4.6.0 suffix:
suffix: description:
description: - Optional suffix for virtual environment and executable names.
- Optional suffix for virtual environment and executable names. - "B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change."
- "B(Warning:) C(pipx) documentation states this is an B(experimental) feature subject to change." type: str
type: str version_added: 9.3.0
version_added: 9.3.0 global:
global: version_added: 9.4.0
version_added: 9.4.0 spec_metadata:
spec_metadata: description:
description: - Spec metadata file for O(state=install_all).
- 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
- This content of the file is usually generated with C(pipx list --json), and it can be obtained with M(community.general.pipx_info) O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output).
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
type: path version_added: 9.4.0
version_added: 9.4.0
notes: notes:
- > - >
This first implementation does not verify whether a specified version constraint has been installed or not. 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, Hence, when using version operators, C(pipx) module will always try to execute the operation,
even when the application was previously installed. even when the application was previously installed.
This feature will be added in the future. This feature will be added in the future.
author: author:
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
''' """
EXAMPLES = ''' EXAMPLES = """
---
- name: Install tox - name: Install tox
community.general.pipx: community.general.pipx:
name: tox name: tox
@ -181,14 +181,14 @@ EXAMPLES = '''
- name: Install multiple packages from list - name: Install multiple packages from list
vars: vars:
pipx_packages: pipx_packages:
- pycowsay - pycowsay
- black - black
- tox - tox
community.general.pipx: community.general.pipx:
name: "{{ item }}" name: "{{ item }}"
state: latest state: latest
with_items: "{{ pipx_packages }}" with_items: "{{ pipx_packages }}"
''' """
import json import json

77
plugins/modules/pipx_info.py
View File

@ -9,45 +9,46 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = """
--- ---
module: pipx_info module: pipx_info
short_description: Rretrieves information about applications installed with pipx short_description: Rretrieves information about applications installed with pipx
version_added: 5.6.0 version_added: 5.6.0
description: 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: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.attributes.info_module - community.general.attributes.info_module
- community.general.pipx - community.general.pipx
options: options:
name: name:
description: description:
- Name of an application installed with C(pipx). - Name of an application installed with C(pipx).
type: str type: str
include_deps: include_deps:
description: description:
- Include dependent packages in the output. - Include dependent packages in the output.
type: bool type: bool
default: false default: false
include_injected: include_injected:
description: description:
- Include injected packages in the output. - Include injected packages in the output.
type: bool type: bool
default: false default: false
include_raw: include_raw:
description: description:
- Returns the raw output of C(pipx list --json). - Returns the raw output of C(pipx list --json).
- The raw output is not affected by O(include_deps) or O(include_injected). - The raw output is not affected by O(include_deps) or O(include_injected).
type: bool type: bool
default: false default: false
global: global:
version_added: 9.3.0 version_added: 9.3.0
author: author:
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
''' """
EXAMPLES = ''' EXAMPLES = """
---
- name: retrieve all installed applications - name: retrieve all installed applications
community.general.pipx_info: {} community.general.pipx_info: {}
@ -65,9 +66,10 @@ EXAMPLES = '''
community.general.pipx_info: community.general.pipx_info:
name: ansible-lint name: ansible-lint
include_deps: true include_deps: true
''' """
RETURN = ''' RETURN = """
---
application: application:
description: The list of installed applications description: The list of installed applications
returned: success returned: success
@ -107,15 +109,8 @@ cmd:
returned: success returned: success
type: list type: list
elements: str elements: str
sample: [ sample: ["/usr/bin/python3.10", "-m", "pipx", "list", "--include-injected", "--json"]
"/usr/bin/python3.10", """
"-m",
"pipx",
"list",
"--include-injected",
"--json"
]
'''
import json import json

3
plugins/modules/xfconf.py
View File

@ -16,8 +16,7 @@ author:
- "Alexei Znamensky (@russoz)" - "Alexei Znamensky (@russoz)"
short_description: Edit XFCE4 Configurations short_description: Edit XFCE4 Configurations
description: 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 - This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query).
details.
seealso: seealso:
- name: xfconf-query(1) man page - name: xfconf-query(1) man page
description: Manual page of the C(xfconf-query) tool at the XFCE documentation site. description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.