zypper: adjust docs (#9307)

* adjust docs * Update plugins/modules/zypper.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/zypper.py Co-authored-by: Felix Fontein <felix@fontein.de> * Update plugins/modules/zypper_repository.py Co-authored-by: Felix Fontein <felix@fontein.de> --------- Co-authored-by: Felix Fontein <felix@fontein.de>
2024-12-23 21:28:19 +13:00 · 2024-12-23 21:28:19 +13:00 · e809a25486
parent b57fef201e
commit e809a25486
3 changed files with 242 additions and 252 deletions
--- a/plugins/modules/zypper.py
+++ b/plugins/modules/zypper.py
@ -18,8 +18,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type


-DOCUMENTATION = '''
---
+DOCUMENTATION = r"""
 module: zypper
 author:
  - "Patrick Callahan (@dirtyharrycallahan)"
@ -43,10 +42,10 @@ options:
  name:
    description:
      - Package name V(name) or package specifier or a list of either.
-        - Can include a version like V(name=1.0), V(name>3.4) or V(name<=2.7). If a version is given, V(oldpackage) is implied and zypper is allowed to
-          update the package within the version range given.
+      - Can include a version like V(name=1.0), V(name>3.4) or V(name<=2.7). If a version is given, V(oldpackage) is implied and zypper is allowed
+        to update the package within the version range given.
      - You can also pass a url or a local path to a rpm file.
-        - When using O(state=latest), this can be '*', which updates all installed packages.
+      - When using O(state=latest), this can be V(*), which updates all installed packages.
    required: true
    aliases: ['pkg']
    type: list
@ -54,10 +53,10 @@ options:
  state:
    description:
      - V(present) will make sure the package is installed.
-            V(latest)  will make sure the latest version of the package is installed.
-            V(absent)  will make sure the specified package is not installed.
-            V(dist-upgrade) will make sure the latest version of all installed packages from all enabled repositories is installed.
-          - When using V(dist-upgrade), O(name) should be V('*').
+      - V(latest) will make sure the latest version of the package is installed.
+      - V(absent) will make sure the specified package is not installed.
+      - V(dist-upgrade) will make sure the latest version of all installed packages from all enabled repositories is installed.
+      - When using V(dist-upgrade), O(name) should be V(*).
    required: false
    choices: [present, latest, absent, dist-upgrade, installed, removed]
    default: "present"
@ -77,9 +76,8 @@ options:
    type: str
  disable_gpg_check:
    description:
-          - Whether to disable to GPG signature checking of the package
-            signature being installed. Has an effect only if O(state) is
-            V(present) or V(latest).
+      - Whether to disable to GPG signature checking of the package signature being installed. Has an effect only if O(state) is V(present) or
+        V(latest).
    required: false
    default: false
    type: bool
@ -145,16 +143,16 @@ options:
      - Adds C(--clean-deps) option to I(zypper) remove command.
    version_added: '4.6.0'
 notes:
-  - When used with a C(loop:) each package will be processed individually,
-    it is much more efficient to pass the list directly to the O(name) option.
+  - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name)
+    option.
 # informational: requirements for nodes
 requirements:
  - "zypper >= 1.0  # included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0"
  - python-xml
  - rpm
-'''
+"""

-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Install nmap
  community.general.zypper:
    name: nmap
@ -228,7 +226,7 @@ EXAMPLES = '''
    state: present
  environment:
    ZYPP_LOCK_TIMEOUT: 20
-'''
+"""

 import os.path
 import xml
--- a/plugins/modules/zypper_repository.py
+++ b/plugins/modules/zypper_repository.py
@ -11,13 +11,12 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type


-DOCUMENTATION = '''
---
+DOCUMENTATION = r"""
 module: zypper_repository
 author: "Matthias Vogelgesang (@matze)"
 short_description: Add and remove Zypper repositories
 description:
-    - Add or remove Zypper repositories on SUSE and openSUSE
+  - Add or remove Zypper repositories on SUSE and openSUSE.
 extends_documentation_fragment:
  - community.general.attributes
 attributes:
@ -32,23 +31,23 @@ options:
    type: str
  repo:
    description:
-            - URI of the repository or .repo file. Required when state=present.
+      - URI of the repository or full path of a C(.repo) file. Required when O(state=present).
    type: str
  state:
    description:
+      - Whether the repository should exist or not.
      - A source string state.
    choices: ["absent", "present"]
    default: "present"
    type: str
  description:
    description:
-            - A description of the repository
+      - A description of the repository.
    type: str
  disable_gpg_check:
    description:
-            - Whether to disable GPG signature checking of
-              all packages. Has an effect only if O(state=present).
-            - Needs zypper version >= 1.6.2.
+      - Whether to disable GPG signature checking of all packages. Has an effect only if O(state=present).
+      - Needs C(zypper) version >= 1.6.2.
    type: bool
    default: false
  autorefresh:
@ -59,28 +58,26 @@ options:
    aliases: ["refresh"]
  priority:
    description:
-            - Set priority of repository. Packages will always be installed
-              from the repository with the smallest priority number.
-            - Needs zypper version >= 1.12.25.
+      - Set priority of repository. Packages will always be installed from the repository with the smallest priority number.
+      - Needs C(zypper) version >= 1.12.25.
    type: int
  overwrite_multiple:
    description:
-            - Overwrite multiple repository entries, if repositories with both name and
-              URL already exist.
+      - Overwrite multiple repository entries, if repositories with both name and URL already exist.
    type: bool
    default: false
  auto_import_keys:
    description:
      - Automatically import the gpg signing key of the new or changed repository.
      - Has an effect only if O(state=present). Has no effect on existing (unchanged) repositories or in combination with O(state=absent).
-            - Implies runrefresh.
-            - Only works with C(.repo) files if `name` is given explicitly.
+      - Implies O(runrefresh).
+      - Only works with C(.repo) files if O(name) is given explicitly.
    type: bool
    default: false
  runrefresh:
    description:
      - Refresh the package list of the given repository.
-            - Can be used with repo=* to refresh all repositories.
+      - Can be used with O(repo=*) to refresh all repositories.
    type: bool
    default: false
  enabled:
@ -93,9 +90,9 @@ options:
 requirements:
  - "zypper >= 1.0  # included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0"
  - python-xml
-'''
+"""

-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Add NVIDIA repository for graphics drivers
  community.general.zypper_repository:
    name: nvidia-repo
@ -128,7 +125,7 @@ EXAMPLES = '''
    name: my_ci_repo
    state: present
    runrefresh: true
-'''
+"""

 import traceback

--- a/plugins/modules/zypper_repository_info.py
+++ b/plugins/modules/zypper_repository_info.py
@ -10,8 +10,7 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type

-DOCUMENTATION = '''
---
+DOCUMENTATION = r"""
 module: zypper_repository_info
 author: "Tobias Zeuch (@TobiasZeuch181)"
 version_added: 10.0.0
@ -27,15 +26,15 @@ requirements:
  - python-xml
 notes:
  - "For info about packages, use the module M(ansible.builtin.package_facts)."
-'''
+"""

-EXAMPLES = '''
+EXAMPLES = r"""
 - name: List registered repositories and store in variable repositories
  community.general.zypper_repository_info: {}
  register: repodatalist
-'''
+"""

-RETURN = '''
+RETURN = r"""
 repodatalist:
  description:
    - A list of repository descriptions like it is returned by the command C(zypper repos).
@ -46,36 +45,32 @@ repodatalist:
    alias:
      description: The alias of the repository.
      type: str
+      sample: "SLE-Product-SLES"
    autorefresh:
      description: Indicates, if autorefresh is enabled on the repository.
      type: int
+      sample: "1"
    enabled:
-            description: indicates, if the repository is enabled
+      description: Indicates, if the repository is enabled.
      type: int
+      sample: "1"
    gpgcheck:
-            description: indicates, if the GPG signature of the repository meta data is checked
+      description: Indicates, if the GPG signature of the repository meta data is checked.
      type: int
+      sample: "1"
    name:
-            description: the name of the repository
+      description: The name of the repository.
      type: str
+      sample: "SLE-Product-SLES"
    priority:
-            description: the priority of the repository
+      description: The priority of the repository.
      type: int
+      sample: "99"
    url:
      description: The URL of the repository on the internet.
      type: str
-    sample: [
-                {
-                    "alias": "SLE-Product-SLES",
-                    "autorefresh": "1",
-                    "enabled": "1",
-                    "gpgcheck": "1",
-                    "name": "SLE-Product-SLES",
-                    "priority": "99",
-                    "url": "http://repo:50000/repo/SUSE/Products/SLE-Product-SLES/15-SP2/x86_64/product"
-                }
-            ]
-'''
+      sample: "http://repo:50000/repo/SUSE/Products/SLE-Product-SLES/15-SP2/x86_64/product"
+"""


 from ansible_collections.community.general.plugins.module_utils import deps