Various improvements to script module docs (#44637)

This PR includes:
- Use uppercase in descriptions
- Add trailing dot to descriptions
- Grammar/spelling fixes
- Adding names to examples as a best practice
- Simplify structure

lib/ansible/modules/commands/script.py

@@ -1,83 +1,80 @@
-# Copyright: Ansible Project
+# Copyright: (c) 2012, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = """
 ---
 module: script
 version_added: "0.9"
 short_description: Runs a local script on a remote node after transferring it
 description:
-     - "The C(script) module takes the script name followed by a list of
+     - The C(script) module takes the script name followed by a list of space-delimited arguments.
-       space-delimited arguments. "
+     - The local script at path will be transferred to the remote node and then executed.
-     - "The local script at path will be transferred to the remote node and then executed. "
+     - The given script will be processed through the shell environment on the remote node.
-     - "The given script will be processed through the shell environment on the remote node. "
+     - This module does not require python on the remote system, much like the M(raw) module.
-     - "This module does not require python on the remote system, much like
-       the M(raw) module. "
      - This module is also supported for Windows targets.
 options:
   free_form:
     description:
-      - Path to the local script file followed by optional arguments. There is no parameter actually named 'free form'; see the examples!
+      - Path to the local script file followed by optional arguments.
+      - There is no parameter actually named 'free form', see the examples!
     required: true
   creates:
     description:
-      - a filename on remote, when it already exists, this step will B(not) be run.
+      - A filename on the remote node, when it already exists, this step will B(not) be run.
     version_added: "1.5"
   removes:
     description:
-      - a filename on remote, when it does not exist, this step will B(not) be run.
+      - A filename on the remote node, when it does not exist, this step will B(not) be run.
     version_added: "1.5"
   chdir:
     description:
-      - cd into this directory on the remote node before running the script
+      - Change into this directory on the remote node before running the script.
     version_added: "2.4"
   executable:
     description:
-      - Name or path of a executable to invoke the script with
+      - Name or path of a executable to invoke the script with.
     version_added: "2.6"
 notes:
-  - It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
+  - It is usually preferable to write Ansible modules rather than pushing scripts. Convert your script to an Ansible module for bonus points!
-  - The ssh connection plugin will force pseudo-tty allocation via -tt when scripts are executed. pseudo-ttys do not have a stderr channel and all
+  - The C(ssh) connection plugin will force pseudo-tty allocation via C(-tt) when scripts are executed. Pseudo-ttys do not have a stderr channel and all
     stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
-  - This module is also supported for Windows targets.
   - If the path to the local script contains spaces, it needs to be quoted.
+  - This module is also supported for Windows targets.
 author:
     - Ansible Core Team
     - Michael DeHaan
 extends_documentation_fragment:
     - decrypt
-"""
+'''
 
-EXAMPLES = '''
+EXAMPLES = r'''
-# Example from Ansible Playbooks
+- name: Run a script with arguments
-- script: /some/local/script.sh --some-arguments 1234
+  script: /some/local/script.sh --some-argument 1234
 
-# Run a script only if the file does not exists
+- name: Run a script only if file.txt does not exist on the remote node
-- script: /some/local/create_file.sh --some-arguments 1234
+  script: /some/local/create_file.sh --some-argument 1234
   args:
     creates: /the/created/file.txt
 
-# Run a script only if the file exists
+- name: Run a script only if file.txt exists on the remote node
-- script: /some/local/remove_file.sh --some-arguments 1234
+  script: /some/local/remove_file.sh --some-argument 1234
   args:
     removes: /the/removed/file.txt
 
-# Run a script using a executable in a non-system path
+- name: Run a script using an executable in a non-system path
-- script: /some/local/script
+  script: /some/local/script
   args:
     executable: /some/remote/executable
 
-# Run a script using a executable in a system path
+- name: Run a script using an executable in a system path
-- script: /some/local/script.py
+  script: /some/local/script.py
   args:
     executable: python3
 '''