Backport/2.9/docs2 (#63250)

* Concise file module example description (#62932)
A file won't be created by the example, the execution would fail unless the file already exists as specified by the module options

(cherry picked from commit 87a6f8397e)

* Added suffix note to process_name_exact parameter (#62849)

(cherry picked from commit 992b81e8fc)

* Fix broken link to powershell resources (#62845)
The previous link (https://docs.microsoft.com/en-us/powershell/dsc/builtinresource ) is a 404 . MS has a new link https://docs.microsoft.com/en-us/powershell/dsc/resources/resources  with the same content

(cherry picked from commit cae4255a16)

* Update playbooks_environment.rst (#62800)

(cherry picked from commit cea8a222a3)

* Update win_dsc.py (#62863)

(cherry picked from commit 798c5a55fa)

* Adjust documentation for yum clean to use best practices (#62898)
The yum module docs suggested using `shell: yum clean all`, which gives an `ansible-lint` error. Plus, you should use the `command` module unless you need more advanced features than just passing in an arbitrary command. Fixes that problem by using the `command` module in the example instead.

(cherry picked from commit 1e6fd6f54d)

* This should never have been "support:network" (#63068)

(cherry picked from commit 7ae46329f2)

* Add docs on hiding sensitive data in loops (#63096)

(cherry picked from commit 0311897722)

* Doc updates to openssl_certificate and ecs_certificate (#63006)
* Update lib/ansible/modules/crypto/entrust/ecs_certificate.py

Co-Authored-By: Felix Fontein <felix@fontein.de>
(cherry picked from commit e55f46f302)

* Update intro_installation.rst (#62994)

(cherry picked from commit f2214951c5)

* Update xml.py (#63128)
Update example to remove escape characters in front of special characters as it is not needed to add explicitly anymore with latest ansible version

(cherry picked from commit 82a6f9d198)

docs/docsite/rst/installation_guide/intro_installation.rst

@@ -82,8 +82,8 @@ later).
      modules to use. You will still need to set :ref:`ansible_python_interpreter<ansible_python_interpreter>` if the Python
      2 interpreter is not installed to :command:`/usr/bin/python`.
 
-   * Ansible's "raw" module (for executing commands in a quick and dirty way) and the script module
-     don't even need Python installed.  So technically, you can use Ansible to install a compatible
+   * Ansible's :ref:`raw module<raw_module>`, and the :ref:`script module<script_module>`, do not depend
+     on a client side install of Python to run.  Technically, you can use Ansible to install a compatible
      version of Python using the :ref:`raw module<raw_module>`, which then allows you to use everything else.
      For example, if you need to bootstrap Python 2 onto a RHEL-based system, you can install it
      via

docs/docsite/rst/user_guide/playbooks_loops.rst

@@ -317,6 +317,8 @@ When looping over complex data structures, the console output of your task can b
 
 The output of this task will display just the ``name`` field for each ``item`` instead of the entire contents of the multi-line ``{{ item }}`` variable.
 
+.. note:: This is for making console output more readable, not protecting sensitive data. If there is sensitive data in ``loop``, set ``no_log: yes`` on the task to prevent disclosure.
+
 Pausing within a loop
 ---------------------
 .. versionadded:: 2.2

lib/ansible/modules/crypto/entrust/ecs_certificate.py

@@ -31,7 +31,7 @@ requirements:
 options:
     backup:
         description:
-            - Path to store a backup of the initial certificate, if I(path) pointed to an existing file certificate.
+            - Whether a backup should be made for the certificate in I(path).
         type: bool
         default: false
     force:
@@ -44,16 +44,17 @@ options:
         default: false
     path:
         description:
-            - Path to put the certificate file as a PEM encoded cert.
-            - If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested regardless of validity.
-            - If there is already an Entrust certificate at this location, whether it is replaced is dependent upon the I(remaining_days) calculation.
-            - If an existing certificate is being replaced (see I(remaining_days), I(force), I(tracking_id)), the operation taken to replace it is dependent
-              on I(request_type)
+            - The destination path for the generated certificate as a PEM encoded cert.
+            - If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested even if the current
+              certificate is technically valid.
+            - If there is already an Entrust certificate at this location, whether it is replaced is depends on the I(remaining_days) calculation.
+            - If an existing certificate is being replaced (see I(remaining_days), I(force), and I(tracking_id)), whether a new certificate is requested
+              or the existing certificate is renewed or reissued is based on I(request_type).
         type: path
         required: true
     full_chain_path:
         description:
-            - Path to put the full certificate chain of the certificate, intermediates, and roots.
+            - The destination path for the full certificate chain of the certificate, intermediates, and roots.
         type: path
     csr:
         description:
@@ -68,23 +69,23 @@ options:
         type: str
     tracking_id:
         description:
-            - Tracking ID of certificate to reissue or renew.
+            - The tracking ID of the certificate to reissue or renew.
             - I(tracking_id) is invalid if C(request_type=new) or C(request_type=validate_only).
             - If there is a certificate present in I(path) and it is an ECS certificate, I(tracking_id) will be ignored.
-            - If there is not a certificate present in I(path) or there is but it is from another provider, the certificate represented by I(tracking_id) will
+            - If there is no certificate present in I(path) or there is but it is from another provider, the certificate represented by I(tracking_id) will
               be renewed or reissued and saved to I(path).
-            - If there is not a certificate present in I(path) and the I(force) and I(remaining_days) parameters do not indicate a new certificate is needed,
+            - If there is no certificate present in I(path) and the I(force) and I(remaining_days) parameters do not indicate a new certificate is needed,
               the certificate referenced by I(tracking_id) certificate will be saved to I(path).
             - This can be used when a known certificate is not currently present on a server, but you want to renew or reissue it to be managed by an ansible
               playbook. For example, if you specify C(request_type=renew), I(tracking_id) of an issued certificate, and I(path) to a file that does not exist,
-              the first run of a task will download the certificate specified by I(tracking_id) (assuming it is still valid), and future runs of the task will
+              the first run of a task will download the certificate specified by I(tracking_id) (assuming it is still valid). Future runs of the task will
               (if applicable - see I(force) and I(remaining_days)) renew the certificate now present in I(path).
         type: int
     remaining_days:
         description:
             - The number of days the certificate must have left being valid. If C(cert_days < remaining_days) then a new certificate will be
               obtained using I(request_type).
-            - If C(request_type=renew), a renew will fail if the certificate being renewed has been issued within the past 30 days, so do not set a
+            - If C(request_type=renew), a renewal will fail if the certificate being renewed has been issued within the past 30 days, so do not set a
               I(remaining_days) value that is within 30 days of the full lifetime of the certificate being acted upon. (e.g. if you are requesting Certificates
               with a 90 day lifetime, do not set remaining_days to a value C(60) or higher).
             - The I(force) option may be used to ensure that a new certificate is always obtained.
@@ -92,8 +93,8 @@ options:
         default: 30
     request_type:
         description:
-            - Operation performed if I(tracking_id) references a valid certificate to reissue, or there is already a certificate present in I(path) but either
-              I(force) is specified or C(cert_days < remaining_days).
+            - The operation performed if I(tracking_id) references a valid certificate to reissue, or there is already a certificate present in I(path) but
+              either I(force) is specified or C(cert_days < remaining_days).
             - Specifying C(request_type=validate_only) means the request will be validated against the ECS API, but no certificate will be issued.
             - Specifying C(request_type=new) means a certificate request will always be submitted and a new certificate issued.
             - Specifying C(request_type=renew) means that an existing certificate (specified by I(tracking_id) if present, otherwise I(path)) will be renewed.
@@ -112,7 +113,7 @@ options:
         default: new
     cert_type:
         description:
-            - The type of certificate product to request.
+            - Specify the type of certificate requested.
             - If a certificate is being reissued or renewed, this parameter is ignored, and the C(cert_type) of the initial certificate is used.
         type: str
         choices: [ 'STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CODE_SIGNING', 'EV_CODE_SIGNING',
@@ -153,7 +154,7 @@ options:
         description:
             - Organization "O=" to include in the certificate.
             - If I(org) is not specified, the organization from the client represented by I(client_id) is used.
-            - Unless the I(cert_type) is C(PD_SSL), this field may not be specified if the value of I(client_id) is not the primary client of "1". For all
+            - Unless the I(cert_type) is C(PD_SSL), this field may not be specified if the value of I(client_id) is not "1" (the primary client).
               non-primary clients, certificates may only be issued with the organization of that client.
         type: str
     ou:
@@ -180,15 +181,15 @@ options:
         description: Free form tracking information to attach to the record for the certificate.
         type: str
     requester_name:
-        description: Requester name to associate with certificate tracking information.
+        description: The requester name to associate with certificate tracking information.
         type: str
         required: true
     requester_email:
-        description: Requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate.
+        description: The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate.
         type: str
         required: true
     requester_phone:
-        description: Requester phone number to associate with certificate tracking information.
+        description: The requester phone number to associate with certificate tracking information.
         type: str
         required: true
     additional_emails:
@@ -203,49 +204,49 @@ options:
         type: dict
         suboptions:
             text1:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text2:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text3:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text4:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text5:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text6:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text7:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text8:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text9:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text10:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text11:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text12:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text13:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text14:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             text15:
-                description: Custom text field of maximum size 500.
+                description: Custom text field (maximum 500 characters)
                 type: str
             number1:
                 description: Custom number field.
@@ -309,14 +310,15 @@ options:
                 type: str
     cert_expiry:
         description:
-            - The date the certificate should be set to expire, as an RFC3339 compliant date or date-time. For example,
+            - The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example,
               C(2020-02-23), C(2020-02-23T15:00:00.05Z).
             - I(cert_expiry) is only supported for requests of C(request_type=new) or C(request_type=renew). If C(request_type=reissue),
               I(cert_expiry) will be used for the first certificate issuance, but subsequent issuances will have the same expiry as the initial
               certificate.
             - A reissued certificate will always have the same expiry as the original certificate.
-            - Note that only the date (day, month, year) is supported for specifying expiry date. If you choose to specify an expiry time with the expiry date,
-              the time will be adjusted to Eastern Standard Time (EST). This could have the unintended effect of moving your expiry date to the previous day.
+            - Note that only the date (day, month, year) is supported for specifying the expiry date. If you choose to specify an expiry time with the expiry
+              date, the time will be adjusted to Eastern Standard Time (EST). This could have the unintended effect of moving your expiry date to the previous
+              day.
             - Applies only to accounts with a pooling inventory model.
             - Only one of I(cert_expiry) or I(cert_lifetime) may be specified.
         type: str
@@ -461,7 +463,7 @@ EXAMPLES = r'''
 
 RETURN = '''
 filename:
-    description: Path to the generated Certificate.
+    description: The destination path for the generated certificate.
     returned: changed or success
     type: str
     sample: /etc/ssl/crt/www.ansible.com.crt

lib/ansible/modules/crypto/openssl_certificate.py

@@ -470,7 +470,7 @@ options:
 
     entrust_cert_type:
         description:
-            - The type of certificate product to request.
+            - Specify the type of certificate requested.
             - This is only used by the C(entrust) provider.
         type: str
         default: STANDARD_SSL
@@ -519,7 +519,7 @@ options:
 
     entrust_api_client_cert_path:
         description:
-            - The path of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+            - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
             - This is only used by the C(entrust) provider.
             - This is required if the provider is C(entrust).
         type: path
@@ -527,7 +527,7 @@ options:
 
     entrust_api_client_cert_key_path:
         description:
-            - The path of the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+            - The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
             - This is only used by the C(entrust) provider.
             - This is required if the provider is C(entrust).
         type: path
@@ -536,15 +536,15 @@ options:
     entrust_not_after:
         description:
             - The point in time at which the certificate stops being valid.
-            - Time can be specified either as relative time or as absolute timestamp.
+            - Time can be specified either as relative time or as an absolute timestamp.
+            - A valid absolute time format is C(ASN.1 TIME) such as C(2019-06-18).
+            - A valid relative time format is C([+-]timespec) where timespec can be an integer + C([w | d | h | m | s]), such as C(+365d) or C(+32w1d2h)).
             - Time will always be interpreted as UTC.
-            - Note that only the date (day, month, year) is supported for specifying expiry date of the issued certificate.
+            - Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate.
             - The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day
               earlier than expected if a relative time is used.
             - The minimum certificate lifetime is 90 days, and maximum is three years.
-            - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
-              + C([w | d | h | m | s]) (e.g. C(+32w1d2h).
-            - If this value is not specified, the certificate will stop being valid 365 days from now.
+            - If this value is not specified, the certificate will stop being valid 365 days the date of issue.
             - This is only used by the C(entrust) provider.
         type: str
         default: +365d
@@ -552,8 +552,8 @@ options:
 
     entrust_api_specification_path:
         description:
-            - Path to the specification file defining the Entrust Certificate Services (ECS) API.
-            - Can be used to keep a local copy of the specification to avoid downloading it every time the module is used.
+            - The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
+            - You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
             - This is only used by the C(entrust) provider.
         type: path
         default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml

lib/ansible/modules/files/file.py

@@ -126,7 +126,7 @@ EXAMPLES = r'''
     group: foo
     mode: '0644'
 
-- name: Create an insecure file
+- name: Give insecure permissions to an existing file
   file:
     path: /work
     owner: root

lib/ansible/modules/files/xml.py

@@ -225,7 +225,7 @@ EXAMPLES = r'''
 - name: Add several more beers to the 'beers' element and add them before the 'Rochefort 10' element
   xml:
     path: /foo/bar.xml
-    xpath: '/business/beers/beer[text()=\"Rochefort 10\"]'
+    xpath: '/business/beers/beer[text()="Rochefort 10"]'
     insertbefore: yes
     add_children:
     - beer: Old Rasputin

lib/ansible/modules/network/nxos/nxos_ping.py

@@ -18,7 +18,7 @@
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
-                    'supported_by': 'network'}
+                    'supported_by': 'community'}
 
 
 DOCUMENTATION = '''

lib/ansible/modules/packaging/os/yum.py

@@ -225,8 +225,8 @@ notes:
     Use the "yum group list hidden ids" command to see which category of group the group
     you want to install falls into.'
   - 'The yum module does not support clearing yum cache in an idempotent way, so it
-    was decided not to implement it, the only method is to use shell and call the yum
-    command directly, namely "shell: yum clean all"
+    was decided not to implement it, the only method is to use command and call the yum
+    command directly, namely "command: yum clean all"
     https://github.com/ansible/ansible/pull/31450#issuecomment-352889579'
 # informational: requirements for nodes
 requirements:

lib/ansible/modules/windows/win_dsc.py

@@ -64,7 +64,7 @@ options:
     required: true
 notes:
 - By default there are a few builtin resources that come with PowerShell 5.0,
-  see U(https://docs.microsoft.com/en-us/powershell/dsc/builtinresource) for
+  see U(https://docs.microsoft.com/en-us/powershell/dsc/resources/resources) for
   more information on these resources.
 - Custom DSC resources can be installed with M(win_psmodule) using the I(name)
   option.
@@ -92,7 +92,7 @@ EXAMPLES = r'''
     Name: telnet-client
 
 - name: Edit HKCU reg key under specific user
-  win_regedit:
+  win_dsc:
     resource_name: Registry
     Ensure: Present
     Key: HKEY_CURRENT_USER\ExampleKey

lib/ansible/modules/windows/win_wait_for_process.py

@@ -22,7 +22,7 @@ description:
 options:
   process_name_exact:
     description:
-    - The name of the process(es) for which to wait.
+    - The name of the process(es) for which to wait.  The name of the process(es) should not include the file extension suffix.
     type: list
   process_name_pattern:
     description:

lib/ansible/plugins/doc_fragments/ecs_credential.py

@@ -24,18 +24,18 @@ options:
         required: true
     entrust_api_client_cert_path:
         description:
-            - The path of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+            - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
         type: path
         required: true
     entrust_api_client_cert_key_path:
         description:
-            - The path of the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+            - The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
         type: path
         required: true
     entrust_api_specification_path:
         description:
-            - Path to the specification file defining the Entrust Certificate Services (ECS) API.
-            - Can be used to keep a local copy of the specification to avoid downloading it every time the module is used.
+            - The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
+            - You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
         type: path
         default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
 requirements: