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

@@ -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/
+
 '''

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

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
 

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
+- 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:
 - community.general.attributes
 attributes:
@@ -28,20 +33,16 @@ options:
   key:
     type: str
     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
   value:
     type: str
     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:
     type: str
     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]
   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
+    - 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
     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

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

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

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
+    - Exclude files from packing option listed in C(/etc/exclude_packing.rootvg).
-        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
 

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).
+    - 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:
     type: str
     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.
   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)
+    - 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
-              with O(community.general.pipx_info#module:include_raw=true) and obtaining the content from the RV(community.general.pipx_info#module:raw_output).
+      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

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: [
+  sample: ["/usr/bin/python3.10", "-m", "pipx", "list", "--include-injected", "--json"]
-    "/usr/bin/python3.10",
+"""
-    "-m",
-    "pipx",
-    "list",
-    "--include-injected",
-    "--json"
-  ]
-'''
 
 import json
 

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
+- This module allows for the manipulation of Xfce 4 Configuration with the help of C(xfconf-query).
-  details.
 seealso:
 - name: xfconf-query(1) man page
   description: Manual page of the C(xfconf-query) tool at the XFCE documentation site.