Update docs with references to man pages (#8983)

* update docs with references to man pages * reformat module docs * gconftool2/_info: docs adjustments
2024-10-08 09:00:26 +13:00 · 2024-10-08 09:00:26 +13:00 · 5b4f41748d
parent 29a2df8e6b
commit 5b4f41748d
10 changed files with 461 additions and 434 deletions
--- 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/
+
 '''
--- 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.
-  - >
+- 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
@ -42,7 +48,7 @@ options:
      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:
@ -90,6 +96,7 @@ options:
 """

 EXAMPLES = """
+---
 - name: Install collection community.network
  community.general.ansible_galaxy_install:
    type: collection
@ -111,31 +118,31 @@ EXAMPLES = """
    type: collection
    name: community.network:3.0.2
    force: true
-
 """

 RETURN = """
-  type:
+---
+type:
  description: The value of the O(type) parameter.
  type: str
  returned: always
-  name:
+name:
  description: The value of the O(name) parameter.
  type: str
  returned: always
-  dest:
+dest:
  description: The value of the O(dest) parameter.
  type: str
  returned: always
-  requirements_file:
+requirements_file:
  description: The value of the O(requirements_file) parameter.
  type: str
  returned: always
-  force:
+force:
  description: The value of the O(force) parameter.
  type: bool
  returned: always
-  installed_roles:
+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.
@ -151,7 +158,7 @@ RETURN = """
      baztian.xfce: v0.0.3
    /custom/ansible/roles:
      ansistrano.deploy: 3.8.0
-  installed_collections:
+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.
@ -167,14 +174,14 @@ RETURN = """
      community.general: 3.0.2
    /custom/ansible/ansible_collections:
      community.general: 3.1.0
-  new_collections:
+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:
+new_roles:
  description: New roles installed by this module.
  returned: success
  type: dict
--- 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
@ -79,24 +79,30 @@ options:
    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)."
-  - >
+- 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)"
-'''

-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

--- 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:
+RETURN = """
+---
+key:
  description: The key specified in the module parameters.
  returned: success
  type: str
  sample: /desktop/gnome/interface/font_name
-  value_type:
+value_type:
  description: The type of the value that was changed.
  returned: success
  type: str
  sample: string
-  value:
+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:
+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
--- 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)
+- 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:
+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
--- 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
@ -34,15 +35,19 @@ options:
    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
+- 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:
+RETURN = """
+---
+handler:
  description:
  - The handler set as default.
  returned: success
  type: str
  sample: google-chrome.desktop
-  stdout:
+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:
+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
--- 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
@ -67,8 +72,7 @@ options:
    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:
@ -81,18 +85,20 @@ options:
    - 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

--- a/plugins/modules/pipx.py
+++ b/plugins/modules/pipx.py
@ -9,16 +9,16 @@ 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
@ -48,17 +48,16 @@ options:
    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.
+    - 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.
+    - 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
@ -138,21 +137,22 @@ options:
  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).
+    - 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.
 author:
-    - "Alexei Znamensky (@russoz)"
-'''
+- "Alexei Znamensky (@russoz)"
+"""

-EXAMPLES = '''
+EXAMPLES = """
+---
 - name: Install tox
  community.general.pipx:
    name: tox
@ -188,7 +188,7 @@ EXAMPLES = '''
    name: "{{ item }}"
    state: latest
  with_items: "{{ pipx_packages }}"
-'''
+"""


 import json
--- a/plugins/modules/pipx_info.py
+++ b/plugins/modules/pipx_info.py
@ -9,17 +9,17 @@ 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:
@ -44,10 +44,11 @@ options:
  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

--- 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.