mirror of https://github.com/ansible/ansible.git
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 structurepull/44642/head
parent
ce5530e08d
commit
86147d598f
@ -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
|
||||
'''
|
||||
|
Loading…
Reference in New Issue