From fe798e22a647bb4eb2f36ed87ab83d6aebd420a2 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Thu, 20 Apr 2023 16:16:23 +1200 Subject: [PATCH] parted: improve docs (#6338) --- plugins/modules/parted.py | 79 +++++++++++++++++++++------------------ 1 file changed, 42 insertions(+), 37 deletions(-) diff --git a/plugins/modules/parted.py b/plugins/modules/parted.py index ec72bd6f00..8e60381804 100644 --- a/plugins/modules/parted.py +++ b/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 - - align option (except 'undefined') requires parted 2.1 and above - - If the version of parted is below 3.1, it requires a Linux version running - the sysfs file system C(/sys/). + - This module requires C(parted) version 1.8.3 and above. + - Option I(align) (except C(undefined)) requires C(parted) 2.1 or above. + - If the version of C(parted) is below 3.1, it requires a Linux version running + 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 - that will be created. - - Required when performing any action on the disk, except fetching information. + - The partition number being affected. + - 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 - 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. + - 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 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. - - If C(device) already contains different label, it will be changed to C(label) and any previous partitions will be lost. + - Disk label type or partition table to use. + - 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. - - A C(name) must be specified for a 'gpt' partition table. - - Neither C(part_type) nor C(name) may be used with a 'sun' partition table. + - May be specified only with I(label=msdos) or I(label=dvh). + - Neither I(part_type) nor I(name) may be used with I(label=sun). type: str choices: [ extended, logical, primary ] default: primary part_start: description: - - 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 - 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). + - 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 + 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 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, - that is, the "distance" from the start of the disk. Negative numbers - 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%). + - 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 + 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%). 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. - - If set to C(info) the module will only return the device information. + - Whether to create or delete a partition. + - 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. - - Parameter optional, but see notes below about negative C(part_start) values. + - If specified and the partition does not exist, will set filesystem type to given partition. + - 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. - This bug was fixed in parted 3.2.153. If you want to use negative C(part_start), - specify C(fs_type) as well or make sure your system contains newer parted. + - 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 I(part_start), + specify I(fs_type) as well or make sure your system contains newer parted. ''' RETURN = r'''