docs adjustments (#83369)

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:

lib/ansible/modules/debconf.py

@@ -29,24 +29,24 @@ notes:
     - Several questions have to be answered (depending on the package).
       Use 'debconf-show <package>' 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(<package>.prerm  reconfigure <version>),
       C(<package>.config reconfigure <version>) and C(<package>.postinst control <version>) arguments.
     - The main issue is that the C(<package>.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(<package>.config) step if the file
+      C(dpkg-reconfigure) will effectively ignore changes made by debconf.
+    - However as C(dpkg-reconfigure) only executes the C(<package>.config) step if the file
       exists, it is possible to rename it to C(/var/lib/dpkg/info/<package>.config.ignore)
       before executing C(dpkg-reconfigure -f noninteractive <package>) 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:

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:

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"

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

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)  <brian.brazil@boxever.com>

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).

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:

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

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