parted: improve docs (#6338)

plugins/modules/parted.py

@@ -20,10 +20,11 @@ description:
     command line tool. For a full description of the fields and the options
     check the GNU parted manual.
 requirements:
-  - This module requires parted version 1.8.3 and above
+  - This module requires C(parted) version 1.8.3 and above.
-  - align option (except 'undefined') requires parted 2.1 and above
+  - Option I(align) (except C(undefined)) requires C(parted) 2.1 or above.
-  - If the version of parted is below 3.1, it requires a Linux version running
+  - If the version of C(parted) is below 3.1, it requires a Linux version running
-    the sysfs file system C(/sys/).
+    the C(sysfs) file system C(/sys/).
+  - Requires the C(resizepart) command when using the I(resize) parameter.
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
@@ -33,18 +34,21 @@ attributes:
     support: none
 options:
   device:
-    description: The block device (disk) where to operate.
+    description:
+      - The block device (disk) where to operate.
+      - Regular files can also be partitioned, but it is recommended to create a
+        loopback device using C(losetup) to easily access its partitions.
     type: str
     required: true
   align:
-    description: Set alignment for newly created partitions. Use 'undefined' for parted default aligment.
+    description:
+      - Set alignment for newly created partitions. Use C(undefined) for parted default aligment.
     type: str
     choices: [ cylinder, minimal, none, optimal, undefined ]
     default: optimal
   number:
     description:
-    - The number of the partition to work with or the number of the partition
+      - The partition number being affected.
-      that will be created.
       - Required when performing any action on the disk, except fetching information.
     type: int
   unit:
@@ -52,22 +56,23 @@ options:
       - Selects the current default unit that Parted will use to display
         locations and capacities on the disk and to interpret those given by the
         user if they are not suffixed by an unit.
-    - When fetching information about a disk, it is always recommended to specify a unit.
+      - When fetching information about a disk, it is recommended to always specify a unit.
     type: str
     choices: [ s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact ]
     default: KiB
   label:
     description:
-     - Disk label type to use.
+      - Disk label type or partition table to use.
-     - If C(device) already contains different label, it will be changed to C(label) and any previous partitions will be lost.
+      - If I(device) already contains a different label, it will be changed to I(label)
+        and any previous partitions will be lost.
+      - A I(name) must be specified for a C(gpt) partition table.
     type: str
     choices: [ aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun ]
     default: msdos
   part_type:
     description:
-    - May be specified only with 'msdos' or 'dvh' partition tables.
+      - May be specified only with I(label=msdos) or I(label=dvh).
-    - A C(name) must be specified for a 'gpt' partition table.
+      - Neither I(part_type) nor I(name) may be used with I(label=sun).
-    - Neither C(part_type) nor C(name) may be used with a 'sun' partition table.
     type: str
     choices: [ extended, logical, primary ]
     default: primary
@@ -78,7 +83,7 @@ options:
         specify distance from the end of the disk.
       - The distance can be specified with all the units supported by parted
         (except compat) and it is case sensitive, e.g. C(10GiB), C(15%).
-    - Using negative values may require setting of C(fs_type) (see notes).
+      - Using negative values may require setting of I(fs_type) (see notes).
     type: str
     default: 0%
   part_end:
@@ -108,7 +113,7 @@ options:
   fs_type:
     description:
       - If specified and the partition does not exist, will set filesystem type to given partition.
-     - Parameter optional, but see notes below about negative C(part_start) values.
+      - Parameter optional, but see notes below about negative I(part_start) values.
     type: str
     version_added: '0.2.0'
   resize:
@@ -123,9 +128,9 @@ notes:
     installed on the system is before version 3.1, the module queries the kernel
     through C(/sys/) to obtain disk information. In this case the units CHS and
     CYL are not supported.
-  - Negative C(part_start) start values were rejected if C(fs_type) was not given.
+  - Negative I(part_start) start values were rejected if I(fs_type) was not given.
-    This bug was fixed in parted 3.2.153. If you want to use negative C(part_start),
+    This bug was fixed in parted 3.2.153. If you want to use negative I(part_start),
-    specify C(fs_type) as well or make sure your system contains newer parted.
+    specify I(fs_type) as well or make sure your system contains newer parted.
 '''
 
 RETURN = r'''