x*: adjust docs (#9308)

* adjust docs * Update plugins/modules/xml.py Co-authored-by: Felix Fontein <[email protected]> * fix capitalisation * add markup to references of the xe command (xenserver) * add missing markup * Update plugins/modules/xml.py Co-authored-by: Felix Fontein <[email protected]> --------- Co-authored-by: Felix Fontein <[email protected]>
ansible-collections · Dec 23, 2024 · f9bfe4e · f9bfe4e
1 parent 005c8f5
commit f9bfe4e
Show file tree

Hide file tree

Showing 11 changed files with 843 additions and 879 deletions.
diff --git a/plugins/modules/xattr.py b/plugins/modules/xattr.py
@@ -8,14 +8,12 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: xattr
 short_description: Manage user defined extended attributes
 description:
   - Manages filesystem user defined extended attributes.
-  - Requires that extended attributes are enabled on the target filesystem
-    and that the setfattr/getfattr utilities are present.
+  - Requires that extended attributes are enabled on the target filesystem and that the C(setfattr)/C(getfattr) utilities are present.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
@@ -29,7 +27,7 @@
       - The full path of the file/object to get the facts of.
     type: path
     required: true
-    aliases: [ name ]
+    aliases: [name]
   namespace:
     description:
       - Namespace of the named name/key.
@@ -45,27 +43,26 @@
     type: str
   state:
     description:
-      - defines which state you want to do.
-        V(read) retrieves the current value for a O(key) (default)
-        V(present) sets O(path) to O(value), default if value is set
-        V(all) dumps all data
-        V(keys) retrieves all keys
-        V(absent) deletes the key
+      - Defines which state you want to do.
+      - V(read) retrieves the current value for a O(key).
+      - V(present) sets O(path) to O(value), default if value is set.
+      - V(all) dumps all data.
+      - V(keys) retrieves all keys.
+      - V(absent) deletes the key.
     type: str
-    choices: [ absent, all, keys, present, read ]
+    choices: [absent, all, keys, present, read]
     default: read
   follow:
     description:
-      - If V(true), dereferences symlinks and sets/gets attributes on symlink target,
-        otherwise acts on symlink itself.
+      - If V(true), dereferences symlinks and sets/gets attributes on symlink target, otherwise acts on symlink itself.
     type: bool
     default: true
 author:
   - Brian Coca (@bcoca)
-'''
+"""
 
-EXAMPLES = '''
-- name: Obtain the extended attributes  of /etc/foo.conf
+EXAMPLES = r"""
+- name: Obtain the extended attributes of /etc/foo.conf
   community.general.xattr:
     path: /etc/foo.conf
 
@@ -94,7 +91,7 @@
     namespace: trusted
     key: glusterfs.volume-id
     state: absent
-'''
+"""
 
 import os
 

diff --git a/plugins/modules/xbps.py b/plugins/modules/xbps.py
@@ -10,86 +10,78 @@
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: xbps
 short_description: Manage packages with XBPS
 description:
-    - Manage packages with the XBPS package manager.
+  - Manage packages with the XBPS package manager.
 author:
-    - "Dino Occhialini (@dinoocch)"
-    - "Michael Aldridge (@the-maldridge)"
+  - "Dino Occhialini (@dinoocch)"
+  - "Michael Aldridge (@the-maldridge)"
 extends_documentation_fragment:
-    - community.general.attributes
+  - community.general.attributes
 attributes:
-    check_mode:
-        support: full
-    diff_mode:
-        support: none
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
 options:
-    name:
-        description:
-            - Name of the package to install, upgrade, or remove.
-        aliases: [pkg,package]
-        type: list
-        elements: str
-    state:
-        description:
-            - Desired state of the package.
-        default: "present"
-        choices: ["present", "absent", "latest", "installed", "removed"]
-        type: str
-    recurse:
-        description:
-            - When removing a package, also remove its dependencies, provided
-              that they are not required by other packages and were not
-              explicitly installed by a user.
-        type: bool
-        default: false
-    update_cache:
-        description:
-            - Whether or not to refresh the master package lists. This can be
-              run as part of a package installation or as a separate step.
-        type: bool
-        default: true
-    upgrade:
-        description:
-            - Whether or not to upgrade whole system
-        type: bool
-        default: false
-    upgrade_xbps:
-        description:
-            - Whether or not to upgrade the xbps package when necessary.
-              Before installing new packages,
-              xbps requires the user to update the xbps package itself.
-              Thus when this option is set to V(false),
-              upgrades and installations will fail when xbps is not up to date.
-        type: bool
-        default: true
-        version_added: '0.2.0'
-    root:
-        description:
-            - The full path for the target root directory.
-        type: path
-        version_added: '10.2.0'
-    repositories:
-        description:
-            - Repository URL(s) to prepend to the repository list for the
-              package installation.
-              The URL can be a URL to a repository for
-              remote repositories or a path for local repositories.
-        type: list
-        elements: str
-        version_added: '10.2.0'
-    accept_pubkey:
-        description:
-            - Whether or not repository signing keys should be automatically accepted.
-        type: bool
-        default: false
-        version_added: '10.2.0'
-'''
-
-EXAMPLES = '''
+  name:
+    description:
+      - Name of the package to install, upgrade, or remove.
+    aliases: [pkg, package]
+    type: list
+    elements: str
+  state:
+    description:
+      - Desired state of the package.
+    default: "present"
+    choices: ["present", "absent", "latest", "installed", "removed"]
+    type: str
+  recurse:
+    description:
+      - When removing a package, also remove its dependencies, provided that they are not required by other packages and were not explicitly installed
+        by a user.
+    type: bool
+    default: false
+  update_cache:
+    description:
+      - Whether or not to refresh the master package lists. This can be run as part of a package installation or as a separate step.
+    type: bool
+    default: true
+  upgrade:
+    description:
+      - Whether or not to upgrade whole system.
+    type: bool
+    default: false
+  upgrade_xbps:
+    description:
+      - Whether or not to upgrade the xbps package when necessary. Before installing new packages, xbps requires the user to update the xbps package
+        itself. Thus when this option is set to V(false), upgrades and installations will fail when xbps is not up to date.
+    type: bool
+    default: true
+    version_added: '0.2.0'
+  root:
+    description:
+      - The full path for the target root directory.
+    type: path
+    version_added: '10.2.0'
+  repositories:
+    description:
+      - Repository URL(s) to prepend to the repository list for the package installation. The URL can be a URL to a repository for remote repositories
+        or a path for local repositories.
+    type: list
+    elements: str
+    version_added: '10.2.0'
+  accept_pubkey:
+    description:
+      - Whether or not repository signing keys should be automatically accepted.
+    type: bool
+    default: false
+    version_added: '10.2.0'
+"""
+
+EXAMPLES = r"""
 - name: Install package foo (automatically updating the xbps package if needed)
   community.general.xbps:
     name: foo
@@ -151,20 +143,20 @@
     state: present
     repositories: https://repo-default.voidlinux.org/current
     root: /mnt
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 msg:
-    description: Message about results
-    returned: success
-    type: str
-    sample: "System Upgraded"
+  description: Message about results.
+  returned: success
+  type: str
+  sample: "System Upgraded"
 packages:
-    description: Packages that are affected/would be affected
-    type: list
-    sample: ["ansible"]
-    returned: success
-'''
+  description: Packages that are affected/would be affected.
+  type: list
+  sample: ["ansible"]
+  returned: success
+"""
 
 
 import os