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,6 +9,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type

 DOCUMENTATION = """
+---
 module: ansible_galaxy_install
 author:
 - "Alexei Znamensky (@russoz)"
@ -22,6 +23,11 @@ notes:
  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
 extends_documentation_fragment:
@ -90,6 +96,7 @@ options:
 """

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

 RETURN = """
+---
 type:
  description: The value of the O(type) parameter.
  type: str
--- a/plugins/modules/cpanm.py
+++ b/plugins/modules/cpanm.py
@ -10,7 +10,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type


-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: cpanm
 short_description: Manages Perl library dependencies
@ -91,12 +91,18 @@ notes:
  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.
+
+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 = '''
+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,14 +9,19 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type

-DOCUMENTATION = '''
+DOCUMENTATION = """
+---
 module: gconftool2
 author:
 - 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
 attributes:
@ -28,20 +33,16 @@ 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).
+    - The type of value being set. This is ignored unless O(state=present).
    choices: [bool, float, int, string]
  state:
    type: str
@ -53,17 +54,15 @@ options:
    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,7 +70,8 @@ EXAMPLES = """
    value: "Serif 12"
 """

-RETURN = '''
+RETURN = """
+---
 key:
  description: The key specified in the module parameters.
  returned: success
@ -96,8 +96,7 @@ RETURN = '''
  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,7 +7,8 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type

-DOCUMENTATION = '''
+DOCUMENTATION = """
+---
 module: gconftool2_info
 author:
 - "Alexei Znamensky (@russoz)"
@ -24,29 +25,32 @@ options:
    - 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: 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 = '''
+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,7 +7,8 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type

-DOCUMENTATION = '''
+DOCUMENTATION = """
+---
 module: gio_mime
 author:
 - "Alexei Znamensky (@russoz)"
@ -37,12 +38,16 @@ notes:
 - This module is a thin wrapper around the C(gio mime) command (and subcommand).
 - See man gio(1) for more details.
 seealso:
+- name: C(gio) command manual page
+  description: Manual page for the command.
+  link: https://man.archlinux.org/man/gio.1
 - name: GIO Documentation
  description: Reference documentation for the GIO API..
  link: https://docs.gtk.org/gio/
-'''
+"""

 EXAMPLES = """
+---
 - name: Set chrome as the default handler for https
  community.general.gio_mime:
    mime_type: x-scheme-handler/https
@ -50,7 +55,8 @@ EXAMPLES = """
  register: result
 """

-RETURN = '''
+RETURN = """
+---
 handler:
  description:
  - The handler set as default.
@ -69,7 +75,7 @@ RETURN = '''
  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,13 +10,18 @@ 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.
+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
 attributes:
@ -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,7 +9,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type


-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: pipx
 short_description: Manages applications installed with pipx
@ -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,8 +137,8 @@ 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:
@ -150,9 +149,10 @@ notes:
  This feature will be added in the future.
 author:
 - "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,7 +9,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type


-DOCUMENTATION = '''
+DOCUMENTATION = """
 ---
 module: pipx_info
 short_description: Rretrieves information about applications installed with pipx
@ -45,9 +45,10 @@ options:
    version_added: 9.3.0
 author:
 - "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.