[2.11] Use correct markup in documentation (#76575)

* Use correct markup in documentation (#76545)

(cherry picked from commit 9d1898b1ef8a84f53c1a5f243744071b3aee1e42)

* Fix markup.

(cherry picked from commit c24c4790610c5bb244b689b1cfd69f25c18e4ddd)

21 files changed, 50 insertions, 50 deletions

diff --git a/lib/ansible/modules/apt.py b/lib/ansible/modules/apt.py
index d6b038acc6..5caf4dd8e8 100644
--- a/lib/ansible/modules/apt.py
+++ b/lib/ansible/modules/apt.py
@@ -171,7 +171,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 = '''
diff --git a/lib/ansible/modules/dnf.py b/lib/ansible/modules/dnf.py
index da88ade15c..d888423fe1 100644
--- a/lib/ansible/modules/dnf.py
+++ b/lib/ansible/modules/dnf.py
@@ -129,14 +129,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"
@@ -229,7 +229,7 @@ options:
     default: "no"
     version_added: "2.11"
 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
diff --git a/lib/ansible/modules/git.py b/lib/ansible/modules/git.py
index 96810086bd..0262316210 100644
--- a/lib/ansible/modules/git.py
+++ b/lib/ansible/modules/git.py
@@ -85,8 +85,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"
diff --git a/lib/ansible/modules/iptables.py b/lib/ansible/modules/iptables.py
index 03122e07ee..fe12a839b6 100644
--- a/lib/ansible/modules/iptables.py
+++ b/lib/ansible/modules/iptables.py
@@ -25,7 +25,7 @@ description:
     same as the behaviour of the C(iptables) and C(ip6tables) command which
     this module uses internally.
 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:
@@ -309,9 +309,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:
diff --git a/lib/ansible/modules/known_hosts.py b/lib/ansible/modules/known_hosts.py
index 8d4b226f8e..584ac30229 100644
--- a/lib/ansible/modules/known_hosts.py
+++ b/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:
diff --git a/lib/ansible/modules/package.py b/lib/ansible/modules/package.py
index c8f03f063a..9eb01a52c9 100644
--- a/lib/ansible/modules/package.py
+++ b/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,13 +39,13 @@ 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:
     - Whatever is required for the package plugins specific for each system.
 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 = '''
diff --git a/lib/ansible/modules/pip.py b/lib/ansible/modules/pip.py
index 420e3a18fc..cffed006a8 100644
--- a/lib/ansible/modules/pip.py
+++ b/lib/ansible/modules/pip.py
@@ -120,7 +120,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:
diff --git a/lib/ansible/modules/set_fact.py b/lib/ansible/modules/set_fact.py
index fe8eadf1a6..64875676b9 100644
--- a/lib/ansible/modules/set_fact.py
+++ b/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
diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py
index d474aac3ff..7d43f5cbc4 100644
--- a/lib/ansible/modules/stat.py
+++ b/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 ]
@@ -327,15 +327,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:
diff --git a/lib/ansible/modules/systemd.py b/lib/ansible/modules/systemd.py
index eda8d05b3b..16873bd210 100644
--- a/lib/ansible/modules/systemd.py
+++ b/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 ]
@@ -81,7 +81,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).
     - Supports C(check_mode).
 requirements:
     - A system managed by systemd.
@@ -140,7 +140,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: {
diff --git a/lib/ansible/modules/uri.py b/lib/ansible/modules/uri.py
index c21c45f213..499ea48b79 100644
--- a/lib/ansible/modules/uri.py
+++ b/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.
diff --git a/lib/ansible/modules/validate_argument_spec.py b/lib/ansible/modules/validate_argument_spec.py
index 76942aa6e9..873474c3ec 100644
--- a/lib/ansible/modules/validate_argument_spec.py
+++ b/lib/ansible/modules/validate_argument_spec.py
@@ -55,7 +55,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:
diff --git a/lib/ansible/modules/yum.py b/lib/ansible/modules/yum.py
index d417394a9b..ee3e570974 100644
--- a/lib/ansible/modules/yum.py
+++ b/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:
@@ -237,8 +237,8 @@ options:
     default: "yes"
     type: bool
 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
diff --git a/lib/ansible/plugins/callback/tree.py b/lib/ansible/plugins/callback/tree.py
index e7682d5f17..da9c767aa5 100644
--- a/lib/ansible/plugins/callback/tree.py
+++ b/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.
 '''
 
diff --git a/lib/ansible/plugins/connection/ssh.py b/lib/ansible/plugins/connection/ssh.py
index cc2aff8d12..23a4ac9306 100644
--- a/lib/ansible/plugins/connection/ssh.py
+++ b/lib/ansible/plugins/connection/ssh.py
@@ -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:
@@ -241,9 +241,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:
@@ -256,7 +256,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:
@@ -279,7 +279,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:
diff --git a/lib/ansible/plugins/connection/winrm.py b/lib/ansible/plugins/connection/winrm.py
index 82bada26fc..c9d8dbc4c1 100644
--- a/lib/ansible/plugins/connection/winrm.py
+++ b/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
diff --git a/lib/ansible/plugins/doc_fragments/default_callback.py b/lib/ansible/plugins/doc_fragments/default_callback.py
index fd17b260bb..0419196ed7 100644
--- a/lib/ansible/plugins/doc_fragments/default_callback.py
+++ b/lib/ansible/plugins/doc_fragments/default_callback.py
@@ -18,9 +18,9 @@ class ModuleDocFragment(object):
         env:
           - name: DISPLAY_SKIPPED_HOSTS
             deprecated:
-              why: environment variables without "ANSIBLE_" prefix are deprecated
+              why: environment variables without C(ANSIBLE_) prefix are deprecated
               version: "2.12"
-              alternatives: the "ANSIBLE_DISPLAY_SKIPPED_HOSTS" environment variable
+              alternatives: the C(ANSIBLE_DISPLAY_SKIPPED_HOSTS) environment variable
           - name: ANSIBLE_DISPLAY_SKIPPED_HOSTS
         ini:
           - key: display_skipped_hosts
diff --git a/lib/ansible/plugins/doc_fragments/shell_common.py b/lib/ansible/plugins/doc_fragments/shell_common.py
index 5b018000bf..628cc2188d 100644
--- a/lib/ansible/plugins/doc_fragments/shell_common.py
+++ b/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."
diff --git a/lib/ansible/plugins/inventory/ini.py b/lib/ansible/plugins/inventory/ini.py
index be9ec2fce9..6b60c40ae3 100644
--- a/lib/ansible/plugins/inventory/ini.py
+++ b/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/2/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.
diff --git a/lib/ansible/plugins/lookup/inventory_hostnames.py b/lib/ansible/plugins/lookup/inventory_hostnames.py
index a3cff92ea9..f8432752a3 100644
--- a/lib/ansible/plugins/lookup/inventory_hostnames.py
+++ b/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.
diff --git a/lib/ansible/plugins/lookup/sequence.py b/lib/ansible/plugins/lookup/sequence.py
index e2ea219491..7aa254650c 100644
--- a/lib/ansible/plugins/lookup/sequence.py
+++ b/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