Fix various module docs. (#4887) (#4888)

(cherry picked from commit 2dcdd2faca)

Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/modules/cloud/lxd/lxd_container.py

@@ -191,10 +191,10 @@ notes:
     2.1, the later requires python to be installed in the instance which can
     be done with the command module.
   - You can copy a file from the host to the instance
-    with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module and the `lxd` connection plugin.
+    with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module and the C(community.general.lxd) connection plugin.
     See the example below.
   - You can copy a file in the created instance to the localhost
-    with `command=lxc file pull instance_name/dir/filename filename`.
+    with C(command=lxc file pull instance_name/dir/filename filename).
     See the first example below.
 '''
 

plugins/modules/cloud/misc/serverless.py

@@ -107,7 +107,7 @@ state:
   returned: always
 command:
   type: str
-  description: Full `serverless` command run by this module, in case you want to re-run the command outside the module.
+  description: Full C(serverless) command run by this module, in case you want to re-run the command outside the module.
   returned: always
   sample: serverless deploy --stage production
 '''

plugins/modules/cloud/misc/terraform.py

@@ -67,7 +67,7 @@ options:
   state_file:
     description:
       - The path to an existing Terraform state file to use when building plan.
-        If this is not specified, the default `terraform.tfstate` will be used.
+        If this is not specified, the default C(terraform.tfstate) will be used.
       - This option is ignored when plan is specified.
     type: path
   variables_files:
@@ -103,7 +103,7 @@ options:
   force_init:
     description:
       - To avoid duplicating infra, if a state file can't be found this will
-        force a `terraform init`. Generally, this should be turned off unless
+        force a C(terraform init). Generally, this should be turned off unless
         you intend to provision an entirely new Terraform deployment.
     default: false
     type: bool
@@ -149,7 +149,7 @@ options:
     type: int
     version_added: '3.8.0'
 notes:
-   - To just run a `terraform plan`, use check mode.
+   - To just run a C(terraform plan), use check mode.
 requirements: [ "terraform" ]
 author: "Ryan Scott Brown (@ryansb)"
 '''
@@ -205,7 +205,7 @@ EXAMPLES = """
 RETURN = """
 outputs:
   type: complex
-  description: A dictionary of all the TF outputs by their assigned name. Use `.outputs.MyOutputName.value` to access the value.
+  description: A dictionary of all the TF outputs by their assigned name. Use C(.outputs.MyOutputName.value) to access the value.
   returned: on success
   sample: '{"bukkit_arn": {"sensitive": false, "type": "string", "value": "arn:aws:s3:::tf-test-bukkit"}'
   contains:
@@ -223,12 +223,12 @@ outputs:
       description: The value of the output as interpolated by Terraform
 stdout:
   type: str
-  description: Full `terraform` command stdout, in case you want to display it or examine the event log
+  description: Full C(terraform) command stdout, in case you want to display it or examine the event log
   returned: always
   sample: ''
 command:
   type: str
-  description: Full `terraform` command built by this module, in case you want to re-run the command outside the module or debug a problem.
+  description: Full C(terraform) command built by this module, in case you want to re-run the command outside the module or debug a problem.
   returned: always
   sample: terraform apply ...
 """

plugins/modules/cloud/rackspace/rax_mon_check.py

@@ -75,15 +75,15 @@ options:
   target_hostname:
     type: str
     description:
-    - One of `target_hostname` and `target_alias` is required for remote.* checks,
+    - One of I(target_hostname) and I(target_alias) is required for remote.* checks,
       but prohibited for agent.* checks. The hostname this check should target.
       Must be a valid IPv4, IPv6, or FQDN.
   target_alias:
     type: str
     description:
-    - One of `target_alias` and `target_hostname` is required for remote.* checks,
+    - One of I(target_alias) and I(target_hostname) is required for remote.* checks,
       but prohibited for agent.* checks. Use the corresponding key in the entity's
-      `ip_addresses` hash to resolve an IP address to target.
+      I(ip_addresses) hash to resolve an IP address to target.
   details:
     type: dict
     description:

plugins/modules/cloud/scaleway/scaleway_user_data.py

@@ -35,7 +35,7 @@ options:
   user_data:
     type: dict
     description:
-    - User defined data. Typically used with `cloud-init`.
+    - User defined data. Typically used with C(cloud-init).
     - Pass your cloud-init script here as a string
     required: false
 

plugins/modules/clustering/consul/consul_kv.py

@@ -28,14 +28,14 @@ author:
 options:
     state:
         description:
-          - The action to take with the supplied key and value. If the state is 'present' and `value` is set, the key
-            contents will be set to the value supplied and `changed` will be set to `true` only if the value was
-            different to the current contents. If the state is 'present' and `value` is not set, the existing value
-            associated to the key will be returned. The state 'absent' will remove the key/value pair,
-            again 'changed' will be set to true only if the key actually existed
+          - The action to take with the supplied key and value. If the state is C(present) and I(value) is set, the key
+            contents will be set to the value supplied and C(changed) will be set to C(true) only if the value was
+            different to the current contents. If the state is C(present) and I(value) is not set, the existing value
+            associated to the key will be returned. The state C(absent) will remove the key/value pair,
+            again C(changed) will be set to true only if the key actually existed
             prior to the removal. An attempt can be made to obtain or free the
-            lock associated with a key/value pair with the states 'acquire' or
-            'release' respectively. a valid session must be supplied to make the
+            lock associated with a key/value pair with the states C(acquire) or
+            C(release) respectively. a valid session must be supplied to make the
             attempt changed will be true if the attempt is successful, false
             otherwise.
         type: str

plugins/modules/monitoring/datadog/datadog_event.py

@@ -20,7 +20,7 @@ description:
 - "Allows to post events to Datadog (www.datadoghq.com) service."
 - "Uses http://docs.datadoghq.com/api/#events API."
 author:
-- "Artūras `arturaz` Šlajus (@arturaz)"
+- "Artūras 'arturaz' Šlajus (@arturaz)"
 - "Naoya Nakazawa (@n0ts)"
 options:
     api_key:

plugins/modules/net_tools/haproxy.py

@@ -99,7 +99,7 @@ options:
   weight:
     description:
       - The value passed in argument.
-      - If the value ends with the `%` sign, then the new weight will be
+      - If the value ends with the C(%) sign, then the new weight will be
         relative to the initially configured weight.
       - Relative weights are only permitted between 0 and 100% and absolute
         weights are permitted between 0 and 256.

plugins/modules/packaging/language/pip_package_info.py

@@ -17,7 +17,7 @@ options:
   clients:
     description:
       - A list of the pip executables that will be used to get the packages.
-        They can be supplied with the full path or just the executable name, i.e `pip3.7`.
+        They can be supplied with the full path or just the executable name, for example C(pip3.7).
     default: ['pip']
     required: False
     type: list

plugins/modules/packaging/os/apk.py

@@ -62,8 +62,8 @@ options:
     type: bool
     default: no
 notes:
-  - '"name" and "upgrade" are mutually exclusive.'
-  - 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.
+  - 'I(name) and I(upgrade) are mutually exclusive.'
+  - 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 = '''

plugins/modules/packaging/os/homebrew.py

@@ -35,7 +35,7 @@ options:
         elements: str
     path:
         description:
-            - "A ':' separated list of paths to search for 'brew' executable.
+            - "A C(:) separated list of paths to search for C(brew) executable.
               Since a package (I(formula) in homebrew parlance) location is prefixed relative to the actual path of I(brew) command,
               providing an alternative I(brew) path enables managing different set of packages in an alternative location in the system."
         default: '/usr/local/bin:/opt/homebrew/bin'
@@ -70,8 +70,8 @@ options:
         elements: str
         version_added: '0.2.0'
 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.
 '''
 
 EXAMPLES = '''

plugins/modules/packaging/os/openbsd_pkg.py

@@ -70,8 +70,8 @@ options:
         type: bool
         default: no
 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.
 '''
 
 EXAMPLES = '''

plugins/modules/packaging/os/pkgng.py

@@ -102,8 +102,8 @@ options:
 author: "bleader (@bleader)"
 notes:
   - When using pkgsite, be careful that already in cache packages won't be downloaded again.
-  - 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 = '''

plugins/modules/packaging/os/pulp_repo.py

@@ -119,7 +119,7 @@ options:
   repoview:
     description:
       - Whether to generate repoview files for a published repository. Setting
-        this to "yes" automatically activates `generate_sqlite`.
+        this to "yes" automatically activates C(generate_sqlite).
     required: false
     type: bool
     default: no

plugins/modules/packaging/os/zypper.py

@@ -136,8 +136,8 @@ options:
           - Adds C(--clean-deps) option to I(zypper) remove command.
         version_added: '4.6.0'
 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.
 # informational: requirements for nodes
 requirements:
     - "zypper >= 1.0  # included in openSUSE >= 11.1 or SUSE Linux Enterprise Server/Desktop >= 11.0"

plugins/modules/remote_management/hpilo/hponcfg.py

@@ -29,7 +29,7 @@ options:
     type: str
   executable:
     description:
-     - Path to the hponcfg executable (`hponcfg` which uses $PATH).
+     - Path to the hponcfg executable (C(hponcfg) which uses $PATH).
     default: hponcfg
     type: str
   verbose:

plugins/modules/source_control/hg.py

@@ -36,7 +36,7 @@ options:
     force:
         description:
             - Discards uncommitted changes. Runs C(hg update -C).  Prior to
-              1.9, the default was `yes`.
+              1.9, the default was C(yes).
         type: bool
         default: 'no'
     purge:

plugins/modules/storage/zfs/zfs_delegate_admin.py

@@ -17,7 +17,7 @@ description:
   - See the C(zfs allow) section of C(zfs(1M)) for detailed explanations of options.
   - This module attempts to adhere to the behavior of the command line tool as much as possible.
 requirements:
-  - "A ZFS/OpenZFS implementation that supports delegation with `zfs allow`, including: Solaris >= 10, illumos (all
+  - "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all
     versions), FreeBSD >= 8.0R, ZFS on Linux >= 0.7.0."
 options:
   name:

plugins/modules/system/nosh.py

@@ -129,7 +129,7 @@ state:
     type: str
     sample: "reloaded"
 status:
-    description: a dictionary with the key=value pairs returned by `system-control show-json` or C(None) if the service is not loaded
+    description: A dictionary with the key=value pairs returned by C(system-control show-json) or C(None) if the service is not loaded
     returned: success
     type: complex
     contains:

plugins/modules/web_infrastructure/jira.py

@@ -186,7 +186,7 @@ options:
   validate_certs:
     required: false
     description:
-      - Require valid SSL certificates (set to `false` if you'd like to use self-signed certificates)
+      - Require valid SSL certificates (set to C(false) if you'd like to use self-signed certificates)
     default: true
     type: bool