From 4f73d2ff7a3abc33b94bc4bb09b46afd34834e67 Mon Sep 17 00:00:00 2001 From: Alexei Znamensky <103110+russoz@users.noreply.github.com> Date: Tue, 11 Jun 2024 14:16:59 +1200 Subject: [PATCH] docs adjustments (#83369) --- lib/ansible/modules/deb822_repository.py | 33 ++++++++++---------- lib/ansible/modules/debconf.py | 18 +++++------ lib/ansible/modules/debug.py | 2 +- lib/ansible/modules/dnf.py | 39 ++++++++++++------------ lib/ansible/modules/dnf5.py | 24 +++++++-------- lib/ansible/modules/dpkg_selections.py | 2 +- lib/ansible/modules/expect.py | 4 +-- lib/ansible/modules/fetch.py | 4 +-- lib/ansible/modules/file.py | 2 +- lib/ansible/modules/find.py | 12 ++++---- 10 files changed, 70 insertions(+), 70 deletions(-) diff --git a/lib/ansible/modules/deb822_repository.py b/lib/ansible/modules/deb822_repository.py index aff4fd4d504..0fa33c73d70 100644 --- a/lib/ansible/modules/deb822_repository.py +++ b/lib/ansible/modules/deb822_repository.py @@ -8,28 +8,28 @@ DOCUMENTATION = ''' author: 'Ansible Core Team (@ansible)' short_description: 'Add and remove deb822 formatted repositories' description: -- 'Add and remove deb822 formatted repositories in Debian based distributions' +- 'Add and remove deb822 formatted repositories in Debian based distributions.' module: deb822_repository notes: -- This module will not automatically update caches, call the apt module based +- This module will not automatically update caches, call the M(ansible.builtin.apt) module based on the changed state. options: allow_downgrade_to_insecure: description: - Allow downgrading a package that was previously authenticated but - is no longer authenticated + is no longer authenticated. type: bool allow_insecure: description: - - Allow insecure repositories + - Allow insecure repositories. type: bool allow_weak: description: - - Allow repositories signed with a key using a weak digest algorithm + - Allow repositories signed with a key using a weak digest algorithm. type: bool architectures: description: - - 'Architectures to search within repository' + - Architectures to search within repository. type: list elements: str by_hash: @@ -51,7 +51,7 @@ options: components: description: - Components specify different sections of one distribution version - present in a Suite. + present in a C(Suite). type: list elements: str date_max_future: @@ -64,8 +64,8 @@ options: type: bool inrelease_path: description: - - Determines the path to the InRelease file, relative to the normal - position of an InRelease file. + - Determines the path to the C(InRelease) file, relative to the normal + position of an C(InRelease) file. type: str languages: description: @@ -81,8 +81,8 @@ options: type: str pdiffs: description: - - Controls if APT should try to use PDiffs to update old indexes - instead of downloading the new indexes entirely + - Controls if APT should try to use C(PDiffs) to update old indexes + instead of downloading the new indexes entirely. type: bool signed_by: description: @@ -97,21 +97,20 @@ options: Suite can specify an exact path in relation to the URI(s) provided, in which case the Components: must be omitted and suite must end with a slash (C(/)). Alternatively, it may take the form of a - distribution version (e.g. a version codename like disco or artful). + distribution version (for example a version codename like C(disco) or C(artful)). If the suite does not specify a path, at least one component must be present. type: list elements: str targets: description: - - Defines which download targets apt will try to acquire from this - source. + - Defines which download targets apt will try to acquire from this source. type: list elements: str trusted: description: - Decides if a source is considered trusted or if warnings should be - raised before e.g. packages are installed from this source. + raised before, for example packages are installed from this source. type: bool types: choices: @@ -123,7 +122,7 @@ options: elements: str description: - Which types of packages to look for from a given source; either - binary V(deb) or source code V(deb-src) + binary V(deb) or source code V(deb-src). uris: description: - The URIs must specify the base of the Debian distribution archive, @@ -132,7 +131,7 @@ options: elements: str mode: description: - - The octal mode for newly created files in sources.list.d. + - The octal mode for newly created files in C(sources.list.d). type: raw default: '0644' state: diff --git a/lib/ansible/modules/debconf.py b/lib/ansible/modules/debconf.py index 779952ec94d..0ffaf0e79bb 100644 --- a/lib/ansible/modules/debconf.py +++ b/lib/ansible/modules/debconf.py @@ -29,24 +29,24 @@ notes: - Several questions have to be answered (depending on the package). Use 'debconf-show ' on any Debian or derivative with the package installed to see questions/settings available. - - Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords. + - Some distros will always record tasks involving the setting of passwords as changed. This is due to C(debconf-get-selections) masking passwords. - It is highly recommended to add C(no_log=True) to the task while handling sensitive information using this module. - - The debconf module does not reconfigure packages, it just updates the debconf database. + - The M(ansible.builtin.debconf) module does not reconfigure packages, it just updates the debconf database. An additional step is needed (typically with C(notify) if debconf makes a change) to reconfigure the package and apply the changes. - debconf is extensively used for pre-seeding configuration prior to installation + C(debconf) is extensively used for pre-seeding configuration prior to installation rather than modifying configurations. - So, while dpkg-reconfigure does use debconf data, it is not always authoritative + So, while C(dpkg-reconfigure) does use debconf data, it is not always authoritative and you may need to check how your package is handled. - - Also note dpkg-reconfigure is a 3-phase process. It invokes the + - Also note C(dpkg-reconfigure) is a 3-phase process. It invokes the control scripts from the C(/var/lib/dpkg/info) directory with the C(.prerm reconfigure ), C(.config reconfigure ) and C(.postinst control ) arguments. - The main issue is that the C(.config reconfigure) step for many packages will first reset the debconf database (overriding changes made by this module) by checking the on-disk configuration. If this is the case for your package then - dpkg-reconfigure will effectively ignore changes made by debconf. - - However as dpkg-reconfigure only executes the C(.config) step if the file + C(dpkg-reconfigure) will effectively ignore changes made by debconf. + - However as C(dpkg-reconfigure) only executes the C(.config) step if the file exists, it is possible to rename it to C(/var/lib/dpkg/info/.config.ignore) before executing C(dpkg-reconfigure -f noninteractive ) and then restore it. This seems to be compliant with Debian policy for the .config file. @@ -76,12 +76,12 @@ options: value: description: - Value to set the configuration to. - - After Ansible 2.17, C(value) is of type 'raw'. + - After Ansible 2.17, C(value) is of type C(raw). type: raw aliases: [ answer ] unseen: description: - - Do not set 'seen' flag when pre-seeding. + - Do not set C(seen) flag when pre-seeding. type: bool default: false author: diff --git a/lib/ansible/modules/debug.py b/lib/ansible/modules/debug.py index cdaf118cd2d..325d2541c2c 100644 --- a/lib/ansible/modules/debug.py +++ b/lib/ansible/modules/debug.py @@ -14,7 +14,7 @@ description: - This module prints statements during execution and can be useful for debugging variables or expressions without necessarily halting the playbook. -- Useful for debugging together with the 'when:' directive. +- Useful for debugging together with the C(when:) directive. - This module is also supported for Windows targets. version_added: '0.8' options: diff --git a/lib/ansible/modules/dnf.py b/lib/ansible/modules/dnf.py index 2b8d82faf9e..ae53dd9dfcf 100644 --- a/lib/ansible/modules/dnf.py +++ b/lib/ansible/modules/dnf.py @@ -49,14 +49,14 @@ options: state: description: - Whether to install (V(present), V(latest)), or remove (V(absent)) a package. - - Default is V(None), however in effect the default action is V(present) unless the O(autoremove) option is - enabled for this module, then V(absent) is inferred. + - Default is V(None), however in effect the default action is V(present) unless the O(autoremove=true), + then V(absent) is inferred. choices: ['absent', 'present', 'installed', 'removed', 'latest'] type: str enablerepo: description: - - I(Repoid) of repositories to enable for the install/update operation. + - C(Repoid) of repositories to enable for the install/update operation. These repos will not persist beyond the transaction. When specifying multiple repos, separate them with a ",". type: list @@ -65,9 +65,9 @@ options: disablerepo: description: - - I(Repoid) of repositories to disable for the install/update operation. + - C(Repoid) of repositories to disable for the install/update operation. These repos will not persist beyond the transaction. - When specifying multiple repos, separate them with a ",". + When specifying multiple repos, separate them with a C(,). type: list elements: str default: [] @@ -80,7 +80,7 @@ options: disable_gpg_check: description: - Whether to disable the GPG checking of signatures of packages being - installed. Has an effect only if O(state) is V(present) or V(latest). + installed. Has an effect only if O(state=present) or O(state=latest). - This setting affects packages installed from a repository as well as "local" packages installed from the filesystem or a URL. type: bool @@ -105,13 +105,13 @@ options: description: - If V(true), removes all "leaf" packages from the system that were originally installed as dependencies of user-installed packages but which are no longer - required by any such package. Should be used alone or when O(state) is V(absent) + required by any such package. Should be used alone or when O(state=absent). type: bool default: "no" version_added: "2.4" exclude: description: - - Package name(s) to exclude when state=present, or latest. This can be a + - Package name(s) to exclude when O(state=present), or latest. This can be a list or a comma separated string. version_added: "2.7" type: list @@ -120,14 +120,14 @@ options: skip_broken: description: - Skip all unavailable packages or packages with broken dependencies - without raising an error. Equivalent to passing the --skip-broken option. + without raising an error. Equivalent to passing the C(--skip-broken) option. type: bool default: "no" version_added: "2.7" update_cache: description: - Force dnf to check if cache is out of date and redownload if needed. - Has an effect only if O(state) is V(present) or V(latest). + Has an effect only if O(state=present) or O(state=latest). type: bool default: "no" aliases: [ expire-cache ] @@ -135,7 +135,7 @@ options: update_only: description: - When using latest, only update installed packages. Do not install packages. - - Has an effect only if O(state) is V(latest) + - Has an effect only if O(state=present) or O(state=latest). default: "no" type: bool version_added: "2.7" @@ -155,7 +155,7 @@ options: version_added: "2.7" enable_plugin: description: - - I(Plugin) name to enable for the install/update operation. + - C(Plugin) name to enable for the install/update operation. The enabled plugin will not persist beyond the transaction. version_added: "2.7" type: list @@ -163,7 +163,7 @@ options: default: [] disable_plugin: description: - - I(Plugin) name to disable for the install/update operation. + - C(Plugin) name to disable for the install/update operation. The disabled plugins will not persist beyond the transaction. version_added: "2.7" type: list @@ -173,13 +173,14 @@ options: description: - Disable the excludes defined in DNF config files. - If set to V(all), disables all excludes. - - If set to V(main), disable excludes defined in [main] in dnf.conf. + - If set to V(main), disable excludes defined in C([main]) in C(dnf.conf). - If set to V(repoid), disable excludes defined for given repo id. version_added: "2.7" type: str validate_certs: description: - - This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to V(false), the SSL certificates will not be validated. + - This only applies if using a https url as the source of the rpm. For example, for localinstall. + If set to V(false), the SSL certificates will not be validated. - This should only set to V(false) used on personally controlled sites using self-signed certificates as it avoids verifying the source site. type: bool default: "yes" @@ -195,7 +196,7 @@ options: description: - Specify if the named package and version is allowed to downgrade a maybe already installed higher version of that package. - Note that setting allow_downgrade=True can make this module + Note that setting O(allow_downgrade=true) can make this module behave in a non-idempotent way. The task could end up with a set of packages that does not match the complete list of specified packages to install (because dependencies between the downgraded @@ -238,7 +239,7 @@ options: version_added: "2.8" allowerasing: description: - - If V(true) it allows erasing of installed packages to resolve dependencies. + - If V(true) it allows erasing of installed packages to resolve dependencies. required: false type: bool default: "no" @@ -282,11 +283,11 @@ attributes: platform: platforms: rhel notes: - - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the I(name) option. + - When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option. - Group removal doesn't work if the group was installed with Ansible because upstream dnf's API doesn't properly mark groups as installed, therefore upon removal the module is unable to detect that the group is installed - (https://bugzilla.redhat.com/show_bug.cgi?id=1620324) + U(https://bugzilla.redhat.com/show_bug.cgi?id=1620324). requirements: - python3-dnf - for the autoremove option you need dnf >= 2.0.1" diff --git a/lib/ansible/modules/dnf5.py b/lib/ansible/modules/dnf5.py index 4007752adf2..f54bc807924 100644 --- a/lib/ansible/modules/dnf5.py +++ b/lib/ansible/modules/dnf5.py @@ -17,7 +17,7 @@ options: name: description: - "A package name or package specifier with version, like C(name-1.0). - When using state=latest, this can be '*' which means run: dnf -y update. + When using O(state=latest), this can be C(*) which means run: C(dnf -y update). You can also pass a url or a local path to an rpm file. To operate on several packages this can accept a comma separated string of packages or a list of packages." - Comparison operators for package version are valid here C(>), C(<), C(>=), C(<=). Example - C(name >= 1.0). @@ -37,15 +37,15 @@ options: state: description: - Whether to install (V(present), V(latest)), or remove (V(absent)) a package. - - Default is V(None), however in effect the default action is V(present) unless the V(autoremove) option is - enabled for this module, then V(absent) is inferred. + - Default is V(None), however in effect the default action is V(present) unless the O(autoremove=true), + then V(absent) is inferred. choices: ['absent', 'present', 'installed', 'removed', 'latest'] type: str enablerepo: description: - I(Repoid) of repositories to enable for the install/update operation. These repos will not persist beyond the transaction. - When specifying multiple repos, separate them with a ",". + When specifying multiple repos, separate them with a C(,). type: list elements: str default: [] @@ -53,7 +53,7 @@ options: description: - I(Repoid) of repositories to disable for the install/update operation. These repos will not persist beyond the transaction. - When specifying multiple repos, separate them with a ",". + When specifying multiple repos, separate them with a C(,). type: list elements: str default: [] @@ -84,12 +84,12 @@ options: description: - If V(true), removes all "leaf" packages from the system that were originally installed as dependencies of user-installed packages but which are no longer - required by any such package. Should be used alone or when O(state) is V(absent) + required by any such package. Should be used alone or when O(state=absent). type: bool default: "no" exclude: description: - - Package name(s) to exclude when state=present, or latest. This can be a + - Package name(s) to exclude when O(state=present) or O(state=latest). This can be a list or a comma separated string. type: list elements: str @@ -97,20 +97,20 @@ options: skip_broken: description: - Skip all unavailable packages or packages with broken dependencies - without raising an error. Equivalent to passing the --skip-broken option. + without raising an error. Equivalent to passing the C(--skip-broken) option. type: bool default: "no" update_cache: description: - Force dnf to check if cache is out of date and redownload if needed. - Has an effect only if O(state) is V(present) or V(latest). + Has an effect only if O(state=present) or O(state=latest). type: bool default: "no" aliases: [ expire-cache ] update_only: description: - When using latest, only update installed packages. Do not install packages. - - Has an effect only if O(state) is V(latest) + - Has an effect only if O(state=present) or O(state=latest). default: "no" type: bool security: @@ -147,7 +147,7 @@ options: description: - Disable the excludes defined in DNF config files. - If set to V(all), disables all excludes. - - If set to V(main), disable excludes defined in [main] in dnf.conf. + - If set to V(main), disable excludes defined in C([main]) in C(dnf.conf). - If set to V(repoid), disable excludes defined for given repo id. type: str validate_certs: @@ -166,7 +166,7 @@ options: description: - Specify if the named package and version is allowed to downgrade a maybe already installed higher version of that package. - Note that setting allow_downgrade=True can make this module + Note that setting O(allow_downgrade=true) can make this module behave in a non-idempotent way. The task could end up with a set of packages that does not match the complete list of specified packages to install (because dependencies between the downgraded diff --git a/lib/ansible/modules/dpkg_selections.py b/lib/ansible/modules/dpkg_selections.py index b591636802d..6c66f6951f7 100644 --- a/lib/ansible/modules/dpkg_selections.py +++ b/lib/ansible/modules/dpkg_selections.py @@ -11,7 +11,7 @@ DOCUMENTATION = ''' module: dpkg_selections short_description: Dpkg package selection selections description: - - Change dpkg package selection state via --get-selections and --set-selections. + - Change dpkg package selection state via C(--get-selections) and C(--set-selections). version_added: "2.0" author: - Brian Brazil (@brian-brazil) diff --git a/lib/ansible/modules/expect.py b/lib/ansible/modules/expect.py index 614476332b6..760d7148d60 100644 --- a/lib/ansible/modules/expect.py +++ b/lib/ansible/modules/expect.py @@ -70,10 +70,10 @@ notes: - If you want to run a command through the shell (say you are using C(<), C(>), C(|), and so on), you must specify a shell in the command such as C(/bin/bash -c "/path/to/something | grep else"). - - Case insensitive searches are indicated with a prefix of C(?i). + - Case insensitive searches are indicated with a prefix of C((?i)). - The C(pexpect) library used by this module operates with a search window of 2000 bytes, and does not use a multiline regex match. To perform a - start of line bound match, use a pattern like ``(?m)^pattern`` + start of line bound match, use a pattern like C((?m)^pattern). - The M(ansible.builtin.expect) module is designed for simple scenarios. For more complex needs, consider the use of expect code with the M(ansible.builtin.shell) or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation). diff --git a/lib/ansible/modules/fetch.py b/lib/ansible/modules/fetch.py index 66726e3ae39..a5edb767df0 100644 --- a/lib/ansible/modules/fetch.py +++ b/lib/ansible/modules/fetch.py @@ -28,8 +28,8 @@ options: dest: description: - A directory to save the file into. - - For example, if the O(dest) directory is C(/backup) a O(src) file named C(/etc/profile) on host - C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile). + - For example, if O(dest=/backup), then O(src=/etc/profile) on host + C(host.example.com), would save the file into C(/backup/host.example.com/etc/profile). The host name is based on the inventory name. required: yes fail_on_missing: diff --git a/lib/ansible/modules/file.py b/lib/ansible/modules/file.py index 6ba39903a52..60f614698b0 100644 --- a/lib/ansible/modules/file.py +++ b/lib/ansible/modules/file.py @@ -73,7 +73,7 @@ options: - This flag indicates that filesystem links, if they exist, should be followed. - O(follow=yes) and O(state=link) can modify O(src) when combined with parameters such as O(mode). - Previous to Ansible 2.5, this was V(false) by default. - - While creating a symlink with a non-existent destination, set O(follow) to V(false) to avoid a warning message related to permission issues. + - While creating a symlink with a non-existent destination, set O(follow=false) to avoid a warning message related to permission issues. The warning message is added to notify the user that we can not set permissions to the non-existent destination. type: bool default: yes diff --git a/lib/ansible/modules/find.py b/lib/ansible/modules/find.py index 5e8e36a2327..3379718130a 100644 --- a/lib/ansible/modules/find.py +++ b/lib/ansible/modules/find.py @@ -58,8 +58,8 @@ options: contains: description: - A regular expression or pattern which should be matched against the file content. - - If O(read_whole_file) is V(false) it matches against the beginning of the line (uses - V(re.match(\))). If O(read_whole_file) is V(true), it searches anywhere for that pattern + - If O(read_whole_file=false) it matches against the beginning of the line (uses + V(re.match(\))). If O(read_whole_file=true), it searches anywhere for that pattern (uses V(re.search(\))). - Works only when O(file_type) is V(file). type: str @@ -82,7 +82,7 @@ options: file_type: description: - Type of file to select. - - The 'link' and 'any' choices were added in Ansible 2.3. + - The V(link) and V(any) choices were added in Ansible 2.3. type: str choices: [ any, directory, file, link ] default: file @@ -116,7 +116,7 @@ options: restricted to modes that can be applied using the python C(os.chmod) function. - The mode can be provided as an octal such as V("0644") or - as symbolic such as V(u=rw,g=r,o=r) + as symbolic such as V(u=rw,g=r,o=r). type: raw version_added: '2.16' exact_mode: @@ -145,13 +145,13 @@ options: depth: description: - Set the maximum number of levels to descend into. - - Setting recurse to V(false) will override this value, which is effectively depth 1. + - Setting O(recurse=false) will override this value, which is effectively depth 1. - Default is unlimited depth. type: int version_added: "2.6" encoding: description: - - When doing a C(contains) search, determine the encoding of the files to be searched. + - When doing a O(contains) search, determine the encoding of the files to be searched. type: str version_added: "2.17" extends_documentation_fragment: action_common_attributes