Use semantic markup for docs fragments (ansible#81152)

lib/ansible/plugins/doc_fragments/constructed.py

@@ -12,7 +12,7 @@ class ModuleDocFragment(object):
 options:
   strict:
     description:
-        - If C(yes) make invalid entries a fatal error, otherwise skip and continue.
+        - If V(yes) make invalid entries a fatal error, otherwise skip and continue.
         - Since it is possible to use facts in the expressions they might not always be available
           and we ignore those errors by default.
     type: bool
@@ -49,13 +49,13 @@ class ModuleDocFragment(object):
       default_value:
         description:
         - The default value when the host variable's value is an empty string.
-        - This option is mutually exclusive with C(trailing_separator).
+        - This option is mutually exclusive with O(keyed_groups[].trailing_separator).
         type: str
         version_added: '2.12'
       trailing_separator:
         description:
-        - Set this option to I(False) to omit the C(separator) after the host variable when the value is an empty string.
-        - This option is mutually exclusive with C(default_value).
+        - Set this option to V(False) to omit the O(keyed_groups[].separator) after the host variable when the value is an empty string.
+        - This option is mutually exclusive with O(keyed_groups[].default_value).
         type: bool
         default: True
         version_added: '2.12'

lib/ansible/plugins/doc_fragments/files.py

@@ -19,17 +19,17 @@ class ModuleDocFragment(object):
     - The permissions the resulting filesystem object should have.
     - For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
       You must give Ansible enough information to parse them correctly.
-      For consistent results, quote octal numbers (for example, C('644') or C('1777')) so Ansible receives
+      For consistent results, quote octal numbers (for example, V('644') or V('1777')) so Ansible receives
       a string and can do its own conversion from string into number.
-      Adding a leading zero (for example, C(0755)) works sometimes, but can fail in loops and some other circumstances.
+      Adding a leading zero (for example, V(0755)) works sometimes, but can fail in loops and some other circumstances.
     - Giving Ansible a number without following either of these rules will end up with a decimal
       number which will have unexpected results.
-    - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or
-      C(u=rw,g=r,o=r)).
-    - If C(mode) is not specified and the destination filesystem object B(does not) exist, the default C(umask) on the system will be used
+    - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, V(u+rwx) or
+      V(u=rw,g=r,o=r)).
+    - If O(mode) is not specified and the destination filesystem object B(does not) exist, the default C(umask) on the system will be used
       when setting the mode for the newly created filesystem object.
-    - If C(mode) is not specified and the destination filesystem object B(does) exist, the mode of the existing filesystem object will be used.
-    - Specifying C(mode) is the best way to ensure filesystem objects are created with the correct permissions.
+    - If O(mode) is not specified and the destination filesystem object B(does) exist, the mode of the existing filesystem object will be used.
+    - Specifying O(mode) is the best way to ensure filesystem objects are created with the correct permissions.
       See CVE-2020-1736 for further details.
     type: raw
   owner:
@@ -49,24 +49,24 @@ class ModuleDocFragment(object):
   seuser:
     description:
     - The user part of the SELinux filesystem object context.
-    - By default it uses the C(system) policy, where applicable.
-    - When set to C(_default), it will use the C(user) portion of the policy if available.
+    - By default it uses the V(system) policy, where applicable.
+    - When set to V(_default), it will use the C(user) portion of the policy if available.
     type: str
   serole:
     description:
     - The role part of the SELinux filesystem object context.
-    - When set to C(_default), it will use the C(role) portion of the policy if available.
+    - When set to V(_default), it will use the C(role) portion of the policy if available.
     type: str
   setype:
     description:
     - The type part of the SELinux filesystem object context.
-    - When set to C(_default), it will use the C(type) portion of the policy if available.
+    - When set to V(_default), it will use the C(type) portion of the policy if available.
     type: str
   selevel:
     description:
     - The level part of the SELinux filesystem object context.
     - This is the MLS/MCS attribute, sometimes known as the C(range).
-    - When set to C(_default), it will use the C(level) portion of the policy if available.
+    - When set to V(_default), it will use the C(level) portion of the policy if available.
     type: str
   unsafe_writes:
     description:

lib/ansible/plugins/doc_fragments/result_format_callback.py

@@ -31,14 +31,14 @@ class ModuleDocFragment(object):
         name: Configure output for readability
         description:
           - Configure the result format to be more readable
-          - When the result format is set to C(yaml) this option defaults to C(True), and defaults
-            to C(False) when configured to C(json).
-          - Setting this option to C(True) will force C(json) and C(yaml) results to always be pretty
+          - When O(result_format) is set to V(yaml) this option defaults to V(True), and defaults
+            to V(False) when configured to V(json).
+          - Setting this option to V(True) will force V(json) and V(yaml) results to always be pretty
             printed regardless of verbosity.
-          - When set to C(True) and used with the C(yaml) result format, this option will
+          - When set to V(True) and used with the V(yaml) result format, this option will
             modify module responses in an attempt to produce a more human friendly output at the expense
             of correctness, and should not be relied upon to aid in writing variable manipulations
-            or conditionals. For correctness, set this option to C(False) or set the result format to C(json).
+            or conditionals. For correctness, set this option to V(False) or set O(result_format) to V(json).
         type: bool
         default: null
         env:

lib/ansible/plugins/doc_fragments/shell_common.py

@@ -35,11 +35,11 @@ class ModuleDocFragment(object):
   system_tmpdirs:
     description:
        - "List of valid system temporary directories on the managed machine for Ansible to validate
-         C(remote_tmp) against, when specific permissions are needed.  These must be world
+         O(remote_tmp) against, when specific permissions are needed.  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."
-       - When C(remote_tmp) is required to be a system temp dir and it does not match any in the list,
+       - When O(remote_tmp) is required to be a system temp dir and it does not match any in the list,
          the first one from the list will be used instead.
     default: [ /var/tmp, /tmp ]
     type: list

lib/ansible/plugins/doc_fragments/shell_windows.py

@@ -35,7 +35,7 @@ class ModuleDocFragment(object):
     description:
     - Controls if we set the locale for modules when executing on the
       target.
-    - Windows only supports C(no) as an option.
+    - Windows only supports V(no) as an option.
     type: bool
     default: 'no'
     choices: ['no', False]

lib/ansible/plugins/doc_fragments/template_common.py

@@ -29,7 +29,7 @@ class ModuleDocFragment(object):
     description:
     - Path of a Jinja2 formatted template on the Ansible controller.
     - This can be a relative or an absolute path.
-    - The file must be encoded with C(utf-8) but I(output_encoding) can be used to control the encoding of the output
+    - The file must be encoded with C(utf-8) but O(output_encoding) can be used to control the encoding of the output
       template.
     type: path
     required: yes
@@ -82,14 +82,14 @@ class ModuleDocFragment(object):
   trim_blocks:
     description:
     - Determine when newlines should be removed from blocks.
-    - When set to C(yes) the first newline after a block is removed (block, not variable tag!).
+    - When set to V(yes) the first newline after a block is removed (block, not variable tag!).
     type: bool
     default: yes
     version_added: '2.4'
   lstrip_blocks:
     description:
     - Determine when leading spaces and tabs should be stripped.
-    - When set to C(yes) leading spaces and tabs are stripped from the start of a line to a block.
+    - When set to V(yes) leading spaces and tabs are stripped from the start of a line to a block.
     type: bool
     default: no
     version_added: '2.6'
@@ -102,18 +102,18 @@ class ModuleDocFragment(object):
     default: yes
   output_encoding:
     description:
-    - Overrides the encoding used to write the template file defined by C(dest).
+    - Overrides the encoding used to write the template file defined by O(dest).
     - It defaults to C(utf-8), but any encoding supported by python can be used.
     - The source template file must always be encoded using C(utf-8), for homogeneity.
     type: str
     default: utf-8
     version_added: '2.7'
 notes:
 - Including a string that uses a date in the template will result in the template being marked 'changed' each time.
-- Since Ansible 0.9, templates are loaded with C(trim_blocks=True).
+- Since Ansible 0.9, templates are loaded with O(trim_blocks=True).
 - >
   Also, you can override jinja2 settings by adding a special header to template file.
-  i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False)
+  that is C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False)
   which changes the variable interpolation markers to C([% var %]) instead of C({{ var }}).
   This is the best way to prevent evaluation of things that look like, but should not be Jinja2.
 - To find Byte Order Marks in files, use C(Format-Hex <file> -Count 16) on Windows, and use C(od -a -t x1 -N 16 <file>)

lib/ansible/plugins/doc_fragments/url.py

@@ -17,7 +17,7 @@ class ModuleDocFragment(object):
     type: str
   force:
     description:
-      - If C(yes) do not get a cached copy.
+      - If V(yes) do not get a cached copy.
     type: bool
     default: no
   http_agent:
@@ -27,48 +27,48 @@ class ModuleDocFragment(object):
     default: ansible-httpget
   use_proxy:
     description:
-      - If C(no), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
+      - If V(no), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
     type: bool
     default: yes
   validate_certs:
     description:
-      - If C(no), SSL certificates will not be validated.
+      - If V(no), SSL certificates will not be validated.
       - This should only be used on personally controlled sites using self-signed certificates.
     type: bool
     default: yes
   url_username:
     description:
       - The username for use in HTTP basic authentication.
-      - This parameter can be used without I(url_password) for sites that allow empty passwords
+      - This parameter can be used without O(url_password) for sites that allow empty passwords
     type: str
   url_password:
     description:
       - The password for use in HTTP basic authentication.
-      - If the I(url_username) parameter is not specified, the I(url_password) parameter will not be used.
+      - If the O(url_username) parameter is not specified, the O(url_password) parameter will not be used.
     type: str
   force_basic_auth:
     description:
-      - Credentials specified with I(url_username) and I(url_password) should be passed in HTTP Header.
+      - Credentials specified with O(url_username) and O(url_password) should be passed in HTTP Header.
     type: bool
     default: no
   client_cert:
     description:
       - PEM formatted certificate chain file to be used for SSL client authentication.
-      - This file can also include the key as well, and if the key is included, C(client_key) is not required.
+      - This file can also include the key as well, and if the key is included, O(client_key) is not required.
     type: path
   client_key:
     description:
       - PEM formatted file that contains your private key to be used for SSL client authentication.
-      - If C(client_cert) contains both the certificate and key, this option is not required.
+      - If O(client_cert) contains both the certificate and key, this option is not required.
     type: path
   use_gssapi:
     description:
       - Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate
         authentication.
       - Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi) to be installed.
-      - Credentials for GSSAPI can be specified with I(url_username)/I(url_password) or with the GSSAPI env var
+      - Credentials for GSSAPI can be specified with O(url_username)/O(url_password) or with the GSSAPI env var
         C(KRB5CCNAME) that specified a custom Kerberos credential cache.
-      - NTLM authentication is C(not) supported even if the GSSAPI mech for NTLM has been installed.
+      - NTLM authentication is B(not) supported even if the GSSAPI mech for NTLM has been installed.
     type: bool
     default: no
     version_added: '2.11'

lib/ansible/plugins/doc_fragments/url_windows.py

@@ -19,9 +19,9 @@ class ModuleDocFragment:
   follow_redirects:
     description:
     - Whether or the module should follow redirects.
-    - C(all) will follow all redirect.
-    - C(none) will not follow any redirect.
-    - C(safe) will follow only "safe" redirects, where "safe" means that the
+    - V(all) will follow all redirect.
+    - V(none) will not follow any redirect.
+    - V(safe) will follow only "safe" redirects, where "safe" means that the
       client is only doing a C(GET) or C(HEAD) on the URI to which it is being
       redirected.
     - When following a redirected URL, the C(Authorization) header and any
@@ -48,20 +48,20 @@ class ModuleDocFragment:
     description:
     - Specify how many times the module will redirect a connection to an
       alternative URI before the connection fails.
-    - If set to C(0) or I(follow_redirects) is set to C(none), or C(safe) when
+    - If set to V(0) or O(follow_redirects) is set to V(none), or V(safe) when
       not doing a C(GET) or C(HEAD) it prevents all redirection.
     default: 50
     type: int
   timeout:
     description:
     - Specifies how long the request can be pending before it times out (in
       seconds).
-    - Set to C(0) to specify an infinite timeout.
+    - Set to V(0) to specify an infinite timeout.
     default: 30
     type: int
   validate_certs:
     description:
-    - If C(no), SSL certificates will not be validated.
+    - If V(no), SSL certificates will not be validated.
     - This should only be used on personally controlled sites using self-signed
       certificates.
     default: yes
@@ -74,12 +74,12 @@ class ModuleDocFragment:
       C(Cert:\CurrentUser\My\<thumbprint>).
     - The WinRM connection must be authenticated with C(CredSSP) or C(become)
       is used on the task if the certificate file is not password protected.
-    - Other authentication types can set I(client_cert_password) when the cert
+    - Other authentication types can set O(client_cert_password) when the cert
       is password protected.
     type: str
   client_cert_password:
     description:
-    - The password for I(client_cert) if the cert is password protected.
+    - The password for O(client_cert) if the cert is password protected.
     type: str
   force_basic_auth:
     description:
@@ -96,14 +96,14 @@ class ModuleDocFragment:
     type: str
   url_password:
     description:
-    - The password for I(url_username).
+    - The password for O(url_username).
     type: str
   use_default_credential:
     description:
     - Uses the current user's credentials when authenticating with a server
       protected with C(NTLM), C(Kerberos), or C(Negotiate) authentication.
     - Sites that use C(Basic) auth will still require explicit credentials
-      through the I(url_username) and I(url_password) options.
+      through the O(url_username) and O(url_password) options.
     - The module will only have access to the user's credentials if using
       C(become) with a password, you are connecting with SSH using a password,
       or connecting with WinRM using C(CredSSP) or C(Kerberos with delegation).
@@ -114,29 +114,29 @@ class ModuleDocFragment:
     type: bool
   use_proxy:
     description:
-    - If C(no), it will not use the proxy defined in IE for the current user.
+    - If V(no), it will not use the proxy defined in IE for the current user.
     default: yes
     type: bool
   proxy_url:
     description:
     - An explicit proxy to use for the request.
-    - By default, the request will use the IE defined proxy unless I(use_proxy)
-      is set to C(no).
+    - By default, the request will use the IE defined proxy unless O(use_proxy)
+      is set to V(no).
     type: str
   proxy_username:
     description:
     - The username to use for proxy authentication.
     type: str
   proxy_password:
     description:
-    - The password for I(proxy_username).
+    - The password for O(proxy_username).
     type: str
   proxy_use_default_credential:
     description:
     - Uses the current user's credentials when authenticating with a proxy host
       protected with C(NTLM), C(Kerberos), or C(Negotiate) authentication.
     - Proxies that use C(Basic) auth will still require explicit credentials
-      through the I(proxy_username) and I(proxy_password) options.
+      through the O(proxy_username) and O(proxy_password) options.
     - The module will only have access to the user's credentials if using
       C(become) with a password, you are connecting with SSH using a password,
       or connecting with WinRM using C(CredSSP) or C(Kerberos with delegation).

lib/ansible/plugins/doc_fragments/vars_plugin_staging.py

@@ -14,10 +14,10 @@ class ModuleDocFragment(object):
   stage:
     description:
       - Control when this vars plugin may be executed.
-      - Setting this option to C(all) will run the vars plugin after importing inventory and whenever it is demanded by a task.
-      - Setting this option to C(task) will only run the vars plugin whenever it is demanded by a task.
-      - Setting this option to C(inventory) will only run the vars plugin after parsing inventory.
-      - If this option is omitted, the global I(RUN_VARS_PLUGINS) configuration is used to determine when to execute the vars plugin.
+      - Setting this option to V(all) will run the vars plugin after importing inventory and whenever it is demanded by a task.
+      - Setting this option to V(task) will only run the vars plugin whenever it is demanded by a task.
+      - Setting this option to V(inventory) will only run the vars plugin after parsing inventory.
+      - If this option is omitted, the global C(RUN_VARS_PLUGINS) configuration is used to determine when to execute the vars plugin.
     choices: ['all', 'task', 'inventory']
     version_added: "2.10"
     type: str