Use correct markup in documentation (#76545)

lib/ansible/modules/add_host.py

@@ -62,7 +62,7 @@ notes:
 - Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source',
   because you can now have multiple sources.  An example was added that shows how to partially restore the previous behaviour.
 - Though this module does not change the remote host, we do provide 'changed' status as it can be useful for those trying to track inventory changes.
-- The hosts added will not bypass the ``--limit`` from the command line, so both of those need to be in agreement to make them available as play targets.
+- The hosts added will not bypass the C(--limit) from the command line, so both of those need to be in agreement to make them available as play targets.
   They are still available from hostvars and for delegation as a normal part of the inventory.
 seealso:
 - module: ansible.builtin.group_by

lib/ansible/modules/apt.py

@@ -202,7 +202,7 @@ notes:
    - The apt-get commandline supports implicit regex matches here but we do not because it can let typos through easier
      (If you typo C(foo) as C(fo) apt-get would install packages that have "fo" in their name with a warning and a prompt for the user.
      Since we don't have warnings and prompts before installing we disallow this.Use an explicit fnmatch pattern if you want wildcarding)
-   - When used with a `loop:` each package will be processed individually, it is much more efficient to pass the list directly to the `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 I(name) option.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/dnf.py

@@ -132,14 +132,14 @@ options:
   security:
     description:
       - If set to C(yes), and C(state=latest) then only installs updates that have been marked security related.
-      - Note that, similar to ``dnf upgrade-minimal``, this filter applies to dependencies as well.
+      - Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well.
     type: bool
     default: "no"
     version_added: "2.7"
   bugfix:
     description:
       - If set to C(yes), and C(state=latest) then only installs updates that have been marked bugfix related.
-      - Note that, similar to ``dnf upgrade-minimal``, this filter applies to dependencies as well.
+      - Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well.
     default: "no"
     type: bool
     version_added: "2.7"
@@ -262,7 +262,7 @@ attributes:
     platform:
         platforms: rhel
 notes:
-  - When used with a `loop:` each package will be processed individually, it is much more efficient to pass the list directly to the `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 I(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

lib/ansible/modules/git.py

@@ -95,8 +95,8 @@ options:
         description:
             - If C(yes), any modified files in the working
               repository will be discarded.  Prior to 0.7, this was always
-              'yes' and could not be disabled.  Prior to 1.9, the default was
-              `yes`.
+              C(yes) and could not be disabled.  Prior to 1.9, the default was
+              C(yes).
         type: bool
         default: 'no'
         version_added: "0.7"

lib/ansible/modules/iptables.py

@@ -33,7 +33,7 @@ attributes:
     platform:
         platforms: linux
 notes:
-  - This module just deals with individual rules.If you need advanced
+  - This module just deals with individual rules. If you need advanced
     chaining of rules the recommended way is to template the iptables restore
     file.
 options:
@@ -317,9 +317,9 @@ options:
   limit:
     description:
       - Specifies the maximum average number of matches to allow per second.
-      - The number can specify units explicitly, using `/second', `/minute',
-        `/hour' or `/day', or parts of them (so `5/second' is the same as
-        `5/s').
+      - The number can specify units explicitly, using C(/second), C(/minute),
+        C(/hour) or C(/day), or parts of them (so C(5/second) is the same as
+        C(5/s)).
     type: str
   limit_burst:
     description:

lib/ansible/modules/known_hosts.py

@@ -34,7 +34,7 @@ options:
       - Specifically, the key should not match the format that is found in an SSH pubkey file, but should rather have the hostname prepended to a
         line that includes the pubkey, the same way that it would appear in the known_hosts file. The value prepended to the line must also match
         the value of the name parameter.
-      - Should be of format `<hostname[,IP]> ssh-rsa <pubkey>`.
+      - Should be of format C(<hostname[,IP]> ssh-rsa <pubkey>).
       - For custom SSH port, C(key) needs to specify port as well. See example section.
     type: str
   path:

lib/ansible/modules/package.py

@@ -19,8 +19,8 @@ short_description: Generic OS package manager
 description:
     - This modules manages packages on a target without specifying a package manager module (like M(ansible.builtin.yum), M(ansible.builtin.apt), ...).
       It is convenient to use in an heterogeneous environment of machines without having to create a specific task for
-      each package manager. `package` calls behind the module for the package manager used by the operating system
-      discovered by the module M(ansible.builtin.setup).  If `setup` was not yet run, `package` will run it.
+      each package manager. C(package) calls behind the module for the package manager used by the operating system
+      discovered by the module M(ansible.builtin.setup).  If C(setup) was not yet run, C(package) will run it.
     - This module acts as a proxy to the underlying package manager module. While all arguments will be passed to the
       underlying module, not all modules support the same arguments. This documentation only covers the minimum intersection
       of module arguments that all packaging modules support.
@@ -39,7 +39,7 @@ options:
     required: true
   use:
     description:
-      - The required package manager module to use (`yum`, `apt`, and so on). The default 'auto' will use existing facts or try to autodetect it.
+      - The required package manager module to use (C(yum), C(apt), and so on). The default 'auto' will use existing facts or try to autodetect it.
       - You should only use this field if the automatic selection is not working for some reason.
     default: auto
 requirements:
@@ -64,7 +64,7 @@ attributes:
         details: The support depends on the availability for the specific plugin for each platform and if fact gathering is able to detect it
         platforms: all
 notes:
-    - While `package` abstracts package managers to ease dealing with multiple distributions, package name often differs for the same software.
+    - While C(package) abstracts package managers to ease dealing with multiple distributions, package name often differs for the same software.
 
 '''
 EXAMPLES = '''

lib/ansible/modules/pip.py

@@ -129,7 +129,7 @@ notes:
      run the actual pip command, so it can use any pip version you specify with I(executable).
      By default, it uses the pip version for the Ansible Python interpreter. For example, pip3 on python 3, and pip2 or pip on python 2.
    - The interpreter used by Ansible
-     (see :ref:`ansible_python_interpreter<ansible_python_interpreter>`)
+     (see R(ansible_python_interpreter, ansible_python_interpreter))
      requires the setuptools package, regardless of the version of pip set with
      the I(executable) option.
 requirements:

lib/ansible/modules/service.py

@@ -23,7 +23,7 @@ description:
       (such as M(ansible.builtin.systemd) and M(ansible.builtin.sysvinit)).
       This allows management of a heterogeneous environment of machines without creating a specific task for
       each service manager. The module to be executed is determined by the I(use) option, which defaults to the
-      service manager discovered by M(ansible.builtin.setup).  If `setup` was not yet run, this module may run it.
+      service manager discovered by M(ansible.builtin.setup).  If C(setup) was not yet run, this module may run it.
     - For Windows targets, use the M(ansible.windows.win_service) module instead.
 options:
     name:

lib/ansible/modules/set_fact.py

@@ -22,7 +22,7 @@ description:
 options:
   key_value:
     description:
-      - "The C(set_fact) module takes ``key=value`` pairs or ``key: value``(YAML notation) as variables to set in the playbook scope.
+      - "The C(set_fact) module takes C(key=value) pairs or C(key: value) (YAML notation) as variables to set in the playbook scope.
         The 'key' is the resulting variable name and the value is, of course, the value of said variable."
       - You can create multiple variables at once, by supplying multiple pairs, but do NOT mix notations.
     required: true

lib/ansible/modules/stat.py

@@ -48,8 +48,8 @@ options:
     description:
       - Use file magic and return data about the nature of the file. this uses
         the 'file' utility found on most Linux/Unix systems.
-      - This will add both `mime_type` and 'charset' fields to the return, if possible.
-      - In Ansible 2.3 this option changed from 'mime' to 'get_mime' and the default changed to 'Yes'.
+      - This will add both C(mime_type) and C(charset) fields to the return, if possible.
+      - In Ansible 2.3 this option changed from I(mime) to I(get_mime) and the default changed to C(yes).
     type: bool
     default: yes
     aliases: [ mime, mime_type, mime-type ]
@@ -334,15 +334,15 @@ stat:
         mimetype:
             description: file magic data or mime-type
             returned: success, path exists and user can read stats and
-                installed python supports it and the `mime` option was true, will
-                return 'unknown' on error.
+                installed python supports it and the I(mime) option was true, will
+                return C(unknown) on error.
             type: str
             sample: application/pdf; charset=binary
         charset:
             description: file character set or encoding
             returned: success, path exists and user can read stats and
-                installed python supports it and the `mime` option was true, will
-                return 'unknown' on error.
+                installed python supports it and the I(mime) option was true, will
+                return C(unknown) on error.
             type: str
             sample: us-ascii
         readable:

lib/ansible/modules/systemd.py

@@ -64,7 +64,7 @@ options:
             - "For systemd to work with 'user', the executing user must have its own instance of dbus started and accessible (systemd requirement)."
             - "The user dbus process is normally started during normal login, but not during the run of Ansible tasks.
               Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error."
-            - The user must have access, normally given via setting the ``XDG_RUNTIME_DIR`` variable, see example below.
+            - The user must have access, normally given via setting the C(XDG_RUNTIME_DIR) variable, see example below.
 
         type: str
         choices: [ system, user, global ]
@@ -89,7 +89,7 @@ notes:
     - Since 2.4, one of the following options is required C(state), C(enabled), C(masked), C(daemon_reload), (C(daemon_reexec) since 2.8),
       and all except C(daemon_reload) and (C(daemon_reexec) since 2.8) also require C(name).
     - Before 2.4 you always required C(name).
-    - Globs are not supported in name, i.e ``postgres*.service``.
+    - Globs are not supported in name, i.e C(postgres*.service).
     - The service names might vary by specific OS/distribution
 requirements:
     - A system managed by systemd.
@@ -148,7 +148,7 @@ EXAMPLES = '''
 
 RETURN = '''
 status:
-    description: A dictionary with the key=value pairs returned from `systemctl show`.
+    description: A dictionary with the key=value pairs returned from C(systemctl show).
     returned: success
     type: complex
     sample: {

lib/ansible/modules/uri.py

@@ -52,7 +52,7 @@ options:
     description:
       - The serialization format of the body. When set to C(json), C(form-multipart), or C(form-urlencoded), encodes
         the body argument, if needed, and automatically sets the Content-Type header accordingly.
-      - As of C(2.3) it is possible to override the `Content-Type` header, when
+      - As of v2.3 it is possible to override the C(Content-Type) header, when
         set to C(json) or C(form-urlencoded) via the I(headers) option.
       - The 'Content-Type' header cannot be overridden when using C(form-multipart)
       - C(form-urlencoded) was added in v2.7.

lib/ansible/modules/validate_argument_spec.py

@@ -78,7 +78,7 @@ EXAMPLES = r'''
     - validate_argument_spec:
         argument_spec: "{{lookup('file', 'nakedoptions.yml'}}"
         provided_arguments:
-            but: "that i can define on the include itself, like in it's `vars:` keyword"
+            but: "that i can define on the include itself, like in it's C(vars:) keyword"
 
     - name: the include itself
       vars:

lib/ansible/modules/yum.py

@@ -50,9 +50,9 @@ options:
     version_added: "2.0"
   list:
     description:
-      - "Package name to run the equivalent of yum list --show-duplicates <package> against. In addition to listing packages,
+      - "Package name to run the equivalent of yum list C(--show-duplicates <package>) against. In addition to listing packages,
         use can also list the following: C(installed), C(updates), C(available) and C(repos)."
-      - This parameter is mutually exclusive with C(name).
+      - This parameter is mutually exclusive with I(name).
     type: str
   state:
     description:
@@ -267,8 +267,8 @@ attributes:
     platform:
         platforms: rhel
 notes:
-  - When used with a `loop:` each package will be processed individually,
-    it is much more efficient to pass the list directly to the `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 I(name) option.
   - In versions prior to 1.9.2 this module installed and removed each package
     given to the yum module separately. This caused problems when packages
     specified by filename or url had to be installed or removed together. In

lib/ansible/plugins/callback/tree.py

@@ -15,7 +15,7 @@ DOCUMENTATION = '''
     options:
         directory:
             version_added: '2.11'
-            description: directory that will contain the per host JSON files. Also set by the ``--tree`` option when using adhoc.
+            description: directory that will contain the per host JSON files. Also set by the C(--tree) option when using adhoc.
             ini:
                 - section: callback_tree
                   key: directory
@@ -24,7 +24,7 @@ DOCUMENTATION = '''
             default: "~/.ansible/tree"
             type: path
     description:
-        - "This callback is used by the Ansible (adhoc) command line option `-t|--tree`"
+        - "This callback is used by the Ansible (adhoc) command line option C(-t|--tree)."
         - This produces a JSON dump of events in a directory, a file for each host, the directory used MUST be passed as a command line option.
 '''
 

lib/ansible/plugins/connection/ssh.py

@@ -59,7 +59,7 @@ DOCUMENTATION = '''
       sshpass_prompt:
           description:
               - Password prompt that sshpass should search for. Supported by sshpass 1.06 and up.
-              - Defaults to ``Enter PIN for`` when pkcs11_provider is set.
+              - Defaults to C(Enter PIN for) when pkcs11_provider is set.
           default: ''
           ini:
               - section: 'ssh_connection'
@@ -131,7 +131,7 @@ DOCUMENTATION = '''
               - name: ansible_scp_executable
                 version_added: '2.7'
       scp_extra_args:
-          description: Extra exclusive to the ``scp`` CLI
+          description: Extra exclusive to the C(scp) CLI
           vars:
               - name: ansible_scp_extra_args
           env:
@@ -145,7 +145,7 @@ DOCUMENTATION = '''
             - name: scp_extra_args
           default: ''
       sftp_extra_args:
-          description: Extra exclusive to the ``sftp`` CLI
+          description: Extra exclusive to the C(sftp) CLI
           vars:
               - name: ansible_sftp_extra_args
           env:
@@ -242,9 +242,9 @@ DOCUMENTATION = '''
       control_path:
         description:
           - This is the location to save SSH's ControlPath sockets, it uses SSH's variable substitution.
-          - Since 2.3, if null (default), ansible will generate a unique hash. Use `%(directory)s` to indicate where to use the control dir path setting.
-          - Before 2.3 it defaulted to `control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r`.
-          - Be aware that this setting is ignored if `-o ControlPath` is set in ssh args.
+          - Since 2.3, if null (default), ansible will generate a unique hash. Use ``%(directory)s`` to indicate where to use the control dir path setting.
+          - Before 2.3 it defaulted to ``control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r``.
+          - Be aware that this setting is ignored if C(-o ControlPath) is set in ssh args.
         env:
           - name: ANSIBLE_SSH_CONTROL_PATH
         ini:
@@ -257,7 +257,7 @@ DOCUMENTATION = '''
         default: ~/.ansible/cp
         description:
           - This sets the directory to use for ssh control path if the control path setting is null.
-          - Also, provides the `%(directory)s` variable for the control path setting.
+          - Also, provides the ``%(directory)s`` variable for the control path setting.
         env:
           - name: ANSIBLE_SSH_CONTROL_PATH_DIR
         ini:
@@ -280,7 +280,7 @@ DOCUMENTATION = '''
         description:
             - "Preferred method to use when transferring files over ssh"
             - Setting to 'smart' (default) will try them in order, until one succeeds or they all fail
-            - Using 'piped' creates an ssh pipe with ``dd`` on either side to copy the data
+            - Using 'piped' creates an ssh pipe with C(dd) on either side to copy the data
         choices: ['sftp', 'scp', 'piped', 'smart']
         env: [{name: ANSIBLE_SSH_TRANSFER_METHOD}]
         ini:

lib/ansible/plugins/connection/winrm.py

@@ -12,7 +12,7 @@ DOCUMENTATION = """
     description:
         - Run commands or put/fetch on a target via WinRM
         - This plugin allows extra arguments to be passed that are supported by the protocol but not explicitly defined here.
-          They should take the form of variables declared with the following pattern `ansible_winrm_<option>`.
+          They should take the form of variables declared with the following pattern C(ansible_winrm_<option>).
     version_added: "2.0"
     extends_documentation_fragment:
         - connection_pipelining

lib/ansible/plugins/doc_fragments/shell_common.py

@@ -35,7 +35,7 @@ options:
   system_tmpdirs:
     description:
        - "List of valid system temporary directories on the managed machine for Ansible to choose
-         when it cannot use ``remote_tmp``, normally due to permission issues.  These must be world
+         when it cannot use C(remote_tmp), normally due to permission issues.  These must be world
          readable, writable, and executable. This list should only contain directories which the
          system administrator has pre-created with the proper ownership and permissions otherwise
          security issues can arise."

lib/ansible/plugins/inventory/ini.py

@@ -8,13 +8,13 @@ DOCUMENTATION = '''
     version_added: "2.4"
     short_description: Uses an Ansible INI file as inventory source.
     description:
-        - INI file based inventory, sections are groups or group related with special `:modifiers`.
+        - INI file based inventory, sections are groups or group related with special C(:modifiers).
         - Entries in sections C([group_1]) are hosts, members of the group.
         - Hosts can have variables defined inline as key/value pairs separated by C(=).
         - The C(children) modifier indicates that the section contains groups.
         - The C(vars) modifier indicates that the section contains variables assigned to members of the group.
         - Anything found outside a section is considered an 'ungrouped' host.
-        - Values passed in the INI format using the ``key=value`` syntax are interpreted differently depending on where they are declared within your inventory.
+        - Values passed in the INI format using the C(key=value) syntax are interpreted differently depending on where they are declared within your inventory.
         - When declared inline with the host, INI values are processed by Python's ast.literal_eval function
           (U(https://docs.python.org/3/library/ast.html#ast.literal_eval)) and interpreted as Python literal structures
           (strings, numbers, tuples, lists, dicts, booleans, None). Host lines accept multiple C(key=value) parameters per line.

lib/ansible/plugins/lookup/env.py

@@ -23,7 +23,7 @@ DOCUMENTATION = """
         default: ''
         version_added: '2.13'
     notes:
-        - You can pass the `Undefined` object as C(default) to force an undefined error
+        - You can pass the C(Undefined) object as C(default) to force an undefined error
 """
 
 EXAMPLES = """

lib/ansible/plugins/lookup/inventory_hostnames.py

@@ -14,7 +14,7 @@ DOCUMENTATION = """
     version_added: "1.3"
     short_description: list of inventory hosts matching a host pattern
     description:
-      - "This lookup understands 'host patterns' as used by the `hosts:` keyword in plays
+      - "This lookup understands 'host patterns' as used by the C(hosts:) keyword in plays
         and can return a list of matching hosts from inventory"
     notes:
       - this is only worth for 'hostname patterns' it is easier to loop over the group/group_names variables otherwise.

lib/ansible/plugins/lookup/sequence.py

@@ -15,8 +15,8 @@ DOCUMENTATION = """
       - 'Arguments can be specified as key=value pair strings or as a shortcut form of the arguments string is also accepted: [start-]end[/stride][:format].'
       - 'Numerical values can be specified in decimal, hexadecimal (0x3f8) or octal (0600).'
       - Starting at version 1.9.2, negative strides are allowed.
-      - Generated items are strings. Use Jinja2 filters to convert items to preferred type, e.g. ``{{ 1 + item|int }}``.
-      - See also Jinja2 ``range`` filter as an alternative.
+      - Generated items are strings. Use Jinja2 filters to convert items to preferred type, e.g. C({{ 1 + item|int }}).
+      - See also Jinja2 C(range) filter as an alternative.
     options:
       start:
         description: number at which to start the sequence