From 86147d598fe969222615b104ad5424fcbe326315 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Fri, 24 Aug 2018 15:56:44 +0200 Subject: [PATCH] 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 | 57 ++++++++++++-------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/lib/ansible/modules/commands/script.py b/lib/ansible/modules/commands/script.py index f31c62ec2c8..102ead95474 100644 --- a/lib/ansible/modules/commands/script.py +++ b/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 = """ +DOCUMENTATION = r''' --- 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 - space-delimited arguments. " - - "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. " - - "This module does not require python on the remote system, much like - the M(raw) module. " + - The C(script) module takes the script name followed by a list of space-delimited arguments. + - 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. + - 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! - - 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 + - It is usually preferable to write Ansible modules rather than pushing scripts. Convert your script to an Ansible module for bonus points! + - 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 = ''' -# Example from Ansible Playbooks -- script: /some/local/script.sh --some-arguments 1234 +EXAMPLES = r''' +- name: Run a script with arguments + script: /some/local/script.sh --some-argument 1234 -# Run a script only if the file does not exists -- script: /some/local/create_file.sh --some-arguments 1234 +- name: Run a script only if file.txt does not exist on the remote node + script: /some/local/create_file.sh --some-argument 1234 args: creates: /the/created/file.txt -# Run a script only if the file exists -- script: /some/local/remove_file.sh --some-arguments 1234 +- name: Run a script only if file.txt exists on the remote node + 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 -- script: /some/local/script +- name: Run a script using an executable in a non-system path + script: /some/local/script args: executable: /some/remote/executable -# Run a script using a executable in a system path -- script: /some/local/script.py +- name: Run a script using an executable in a system path + script: /some/local/script.py args: executable: python3 '''