[PR #6338/fe798e22 backport][stable-6] parted: improve docs (#6373)

parted: improve docs (#6338)

(cherry picked from commit fe798e22a6)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

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,66 +34,70 @@ 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.
-    - Required when performing any action on the disk, except fetching information.
     type: int
   unit:
     description:
-    - Selects the current default unit that Parted will use to display
+      - Selects the current default unit that Parted will use to display
-      locations and capacities on the disk and to interpret those given by the
+        locations and capacities on the disk and to interpret those given by the
-      user if they are not suffixed by an unit.
+        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
   part_start:
     description:
-    - Where the partition will start as offset from the beginning of the disk,
+      - Where the partition will start as offset from the beginning of the disk,
-      that is, the "distance" from the start of the disk. Negative numbers
+        that is, the "distance" from the start of the disk. Negative numbers
-      specify distance from the end of the disk.
+        specify distance from the end of the disk.
-    - The distance can be specified with all the units supported by parted
+      - 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%).
+        (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:
     description:
-    - Where the partition will end as offset from the beginning of the disk,
+      - Where the partition will end as offset from the beginning of the disk,
-      that is, the "distance" from the start of the disk. Negative numbers
+        that is, the "distance" from the start of the disk. Negative numbers
-      specify distance from the end of the disk.
+        specify distance from the end of the disk.
-    - The distance can be specified with all the units supported by parted
+      - 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%).
+        (except compat) and it is case sensitive, e.g. C(10GiB), C(15%).
     type: str
     default: 100%
   name:
     description:
-    - Sets the name for the partition number (GPT, Mac, MIPS and PC98 only).
+      - Sets the name for the partition number (GPT, Mac, MIPS and PC98 only).
     type: str
   flags:
     description: A list of the flags that has to be set on the partition.
@@ -100,15 +105,15 @@ options:
     elements: str
   state:
     description:
-    - Whether to create or delete a partition.
+      - Whether to create or delete a partition.
-    - If set to C(info) the module will only return the device information.
+      - If set to C(info) the module will only return the device information.
     type: str
     choices: [ absent, present, info ]
     default: info
   fs_type:
     description:
-     - If specified and the partition does not exist, will set filesystem type to given partition.
+      - 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'''