zfs modules: adjust docs

ansible-collections · Dec 18, 2024 · 782cf29 · 782cf29
1 parent f6dae1f
commit 782cf29
Show file tree

Hide file tree

Showing 3 changed files with 213 additions and 222 deletions.
diff --git a/plugins/modules/zfs.py b/plugins/modules/zfs.py
@@ -9,23 +9,20 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
----
+DOCUMENTATION = r"""
 module: zfs
 short_description: Manage zfs
 description:
-  - Manages ZFS file systems, volumes, clones and snapshots
+  - Manages ZFS file systems, volumes, clones and snapshots.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
   check_mode:
     support: partial
     details:
-      - In certain situations it may report a task as changed that will not be reported
-        as changed when C(check_mode) is disabled.
-      - For example, this might occur when the zpool C(altroot) option is set or when
-        a size is written using human-readable notation, such as V(1M) or V(1024K),
-        instead of as an unqualified byte count, such as V(1048576).
+      - In certain situations it may report a task as changed that will not be reported as changed when C(check_mode) is disabled.
+      - For example, this might occur when the zpool C(altroot) option is set or when a size is written using human-readable notation, such as
+        V(1M) or V(1024K), instead of as an unqualified byte count, such as V(1048576).
   diff_mode:
     support: full
 options:
@@ -36,10 +33,9 @@
     type: str
   state:
     description:
-      - Whether to create (V(present)), or remove (V(absent)) a
-        file system, snapshot or volume. All parents/children
-        will be created/destroyed as needed to reach the desired state.
-    choices: [ absent, present ]
+      - Whether to create (V(present)), or remove (V(absent)) a file system, snapshot or volume. All parents/children will be created/destroyed
+        as needed to reach the desired state.
+    choices: [absent, present]
     required: true
     type: str
   origin:
@@ -53,47 +49,47 @@
     type: dict
     default: {}
 author:
-- Johan Wiren (@johanwiren)
-'''
-
-EXAMPLES = '''
-- name: Create a new file system called myfs in pool rpool with the setuid property turned off
-  community.general.zfs:
-    name: rpool/myfs
-    state: present
-    extra_zfs_properties:
-      setuid: 'off'
-
-- name: Create a new volume called myvol in pool rpool.
-  community.general.zfs:
-    name: rpool/myvol
-    state: present
-    extra_zfs_properties:
-      volsize: 10M
-
-- name: Create a snapshot of rpool/myfs file system.
-  community.general.zfs:
-    name: rpool/myfs@mysnapshot
-    state: present
-
-- name: Create a new file system called myfs2 with snapdir enabled
-  community.general.zfs:
-    name: rpool/myfs2
-    state: present
-    extra_zfs_properties:
-      snapdir: enabled
-
-- name: Create a new file system by cloning a snapshot
-  community.general.zfs:
-    name: rpool/cloned_fs
-    state: present
-    origin: rpool/myfs@mysnapshot
-
-- name: Destroy a filesystem
-  community.general.zfs:
-    name: rpool/myfs
-    state: absent
-'''
+  - Johan Wiren (@johanwiren)
+"""
+
+EXAMPLES = r"""
+  - name: Create a new file system called myfs in pool rpool with the setuid property turned off
+    community.general.zfs:
+      name: rpool/myfs
+      state: present
+      extra_zfs_properties:
+        setuid: 'off'
+
+  - name: Create a new volume called myvol in pool rpool.
+    community.general.zfs:
+      name: rpool/myvol
+      state: present
+      extra_zfs_properties:
+        volsize: 10M
+
+  - name: Create a snapshot of rpool/myfs file system.
+    community.general.zfs:
+      name: rpool/myfs@mysnapshot
+      state: present
+
+  - name: Create a new file system called myfs2 with snapdir enabled
+    community.general.zfs:
+      name: rpool/myfs2
+      state: present
+      extra_zfs_properties:
+        snapdir: enabled
+
+  - name: Create a new file system by cloning a snapshot
+    community.general.zfs:
+      name: rpool/cloned_fs
+      state: present
+      origin: rpool/myfs@mysnapshot
+
+  - name: Destroy a filesystem
+    community.general.zfs:
+      name: rpool/myfs
+      state: absent
+"""
 
 import os
 

diff --git a/plugins/modules/zfs_delegate_admin.py b/plugins/modules/zfs_delegate_admin.py
@@ -8,18 +8,17 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = r'''
----
+DOCUMENTATION = r"""
 module: zfs_delegate_admin
 short_description: Manage ZFS delegated administration (user admin privileges)
 description:
-  - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS
-    operations normally restricted to the superuser.
+  - Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS operations normally restricted
+    to the superuser.
   - See the C(zfs allow) section of V(zfs(1M\)) for detailed explanations of options.
   - This module attempts to adhere to the behavior of the command line tool as much as possible.
 requirements:
-  - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all
-    versions), FreeBSD >= 8.0R, ZFS on Linux >= 0.7.0."
+  - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all versions), FreeBSD >= 8.0R,
+    ZFS on Linux >= 0.7.0."
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
@@ -38,7 +37,7 @@
       - Whether to allow (V(present)), or unallow (V(absent)) a permission.
       - When set to V(present), at least one "entity" param of O(users), O(groups), or O(everyone) are required.
       - When set to V(absent), removes permissions from the specified entities, or removes all permissions if no entity params are specified.
-    choices: [ absent, present ]
+    choices: [absent, present]
     default: present
     type: str
   users:
@@ -59,8 +58,8 @@
   permissions:
     description:
       - The list of permission(s) to delegate (required if O(state=present)).
-      - Supported permissions depend on the ZFS version in use. See for example
-        U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html) for OpenZFS.
+      - Supported permissions depend on the ZFS version in use. See for example U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html)
+        for OpenZFS.
     type: list
     elements: str
   local:
@@ -77,41 +76,41 @@
     type: bool
     default: false
 author:
-- Nate Coraor (@natefoo)
-'''
+  - Nate Coraor (@natefoo)
+"""
 
-EXAMPLES = r'''
-- name: Grant `zfs allow` and `unallow` permission to the `adm` user with the default local+descendents scope
-  community.general.zfs_delegate_admin:
-    name: rpool/myfs
-    users: adm
-    permissions: allow,unallow
+EXAMPLES = r"""
+  - name: Grant `zfs allow` and `unallow` permission to the `adm` user with the default local+descendents scope
+    community.general.zfs_delegate_admin:
+      name: rpool/myfs
+      users: adm
+      permissions: allow,unallow
 
-- name: Grant `zfs send` to everyone, plus the group `backup`
-  community.general.zfs_delegate_admin:
-    name: rpool/myvol
-    groups: backup
-    everyone: true
-    permissions: send
+  - name: Grant `zfs send` to everyone, plus the group `backup`
+    community.general.zfs_delegate_admin:
+      name: rpool/myvol
+      groups: backup
+      everyone: true
+      permissions: send
 
-- name: Grant `zfs send,receive` to users `foo` and `bar` with local scope only
-  community.general.zfs_delegate_admin:
-    name: rpool/myfs
-    users: foo,bar
-    permissions: send,receive
-    local: true
+  - name: Grant `zfs send,receive` to users `foo` and `bar` with local scope only
+    community.general.zfs_delegate_admin:
+      name: rpool/myfs
+      users: foo,bar
+      permissions: send,receive
+      local: true
 
-- name: Revoke all permissions from everyone (permissions specifically assigned to users and groups remain)
-  community.general.zfs_delegate_admin:
-    name: rpool/myfs
-    everyone: true
-    state: absent
-'''
+  - name: Revoke all permissions from everyone (permissions specifically assigned to users and groups remain)
+    community.general.zfs_delegate_admin:
+      name: rpool/myfs
+      everyone: true
+      state: absent
+"""
 
 # This module does not return anything other than the standard
 # changed/state/msg/stdout
-RETURN = '''
-'''
+RETURN = r"""
+"""
 
 from itertools import product