mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Clean up common module docs (#45888)
Some of the older modules have evolved documentation that does not follow a consistent style. This is a clean-up in form and style.
This commit is contained in:
Dag Wieers
Sandra McCann
parent
698c8059e9
commit
04de52da2c
2 changed files with 37 additions and 35 deletions
|
|
@ -3,7 +3,6 @@
|
|||
|
||||
# Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
|
||||
# Copyright: (c) 2016, Toshio Kuratomi <tkuratomi@ansible.com>
|
||||
#
|
||||
# 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
|
||||
|
|
@ -14,10 +13,10 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
|
|||
'status': ['stableinterface'],
|
||||
'supported_by': 'core'}
|
||||
|
||||
DOCUMENTATION = '''
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
module: command
|
||||
short_description: Executes a command on a remote node
|
||||
short_description: Execute commands on targets
|
||||
version_added: historical
|
||||
description:
|
||||
- The C(command) module takes the command name followed by a list of space-delimited arguments.
|
||||
|
|
@ -29,8 +28,9 @@ description:
|
|||
options:
|
||||
free_form:
|
||||
description:
|
||||
- The command module takes a free form command to run. There is no parameter actually named 'free form'.
|
||||
See the examples!
|
||||
- The command module takes a free form command to run.
|
||||
- There is no actual parameter named 'free form'.
|
||||
- See the examples on how to use this module.
|
||||
required: yes
|
||||
argv:
|
||||
description:
|
||||
|
|
@ -50,14 +50,14 @@ options:
|
|||
version_added: "0.6"
|
||||
warn:
|
||||
description:
|
||||
- If command_warnings are on in ansible.cfg, do not warn about this particular line if set to C(no).
|
||||
- Enable or disable task warnings.
|
||||
type: bool
|
||||
default: 'yes'
|
||||
default: yes
|
||||
version_added: "1.8"
|
||||
stdin:
|
||||
version_added: "2.4"
|
||||
description:
|
||||
- Set the stdin of the command directly to the specified value.
|
||||
version_added: "2.4"
|
||||
notes:
|
||||
- If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(shell) module instead.
|
||||
Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to
|
||||
|
|
@ -73,7 +73,7 @@ author:
|
|||
- Michael DeHaan
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
EXAMPLES = r'''
|
||||
- name: return motd to registered var
|
||||
command: cat /etc/motd
|
||||
register: mymotd
|
||||
|
|
@ -102,7 +102,7 @@ EXAMPLES = '''
|
|||
register: myoutput
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
RETURN = r'''
|
||||
cmd:
|
||||
description: the cmd that was run on the remote machine
|
||||
returned: always
|
||||
|
|
|
|||
|
|
@ -1,7 +1,10 @@
|
|||
# Copyright: Ansible Project
|
||||
#!/usr/bin/python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
# Copyright: (c) 2018, Ansible Project
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
|
||||
# # There is no actual shell module source, when you use 'shell' in ansible,
|
||||
# There is no actual shell module source, when you use 'shell' in ansible,
|
||||
# it runs the 'command' module with special arguments and it behaves differently.
|
||||
# See the command source and the comment "#USE_SHELL".
|
||||
|
||||
|
|
@ -14,47 +17,49 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
|
|||
'supported_by': 'core'}
|
||||
|
||||
|
||||
DOCUMENTATION = '''
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
module: shell
|
||||
short_description: Execute commands in nodes.
|
||||
short_description: Execute shell commands on targets
|
||||
description:
|
||||
- The C(shell) module takes the command name followed by a list of space-delimited arguments.
|
||||
It is almost exactly like the M(command) module but runs
|
||||
- It is almost exactly like the M(command) module but runs
|
||||
the command through a shell (C(/bin/sh)) on the remote node.
|
||||
- For Windows targets, use the M(win_shell) module instead.
|
||||
version_added: "0.2"
|
||||
options:
|
||||
free_form:
|
||||
description:
|
||||
- The shell module takes a free form command to run, as a string. There's not an actual
|
||||
option named "free form". See the examples!
|
||||
required: true
|
||||
- The shell module takes a free form command to run, as a string.
|
||||
- There is no actual parameter named 'free form'.
|
||||
- See the examples on how to use this module.
|
||||
required: yes
|
||||
creates:
|
||||
description:
|
||||
- a filename, when it already exists, this step will B(not) be run.
|
||||
- A filename, when it already exists, this step will B(not) be run.
|
||||
removes:
|
||||
description:
|
||||
- a filename, when it does not exist, this step will B(not) be run.
|
||||
- A filename, when it does not exist, this step will B(not) be run.
|
||||
version_added: "0.8"
|
||||
chdir:
|
||||
description:
|
||||
- cd into this directory before running the command
|
||||
- Change into this directory before running the command.
|
||||
version_added: "0.6"
|
||||
executable:
|
||||
description:
|
||||
- change the shell used to execute the command. Should be an absolute path to the executable.
|
||||
- Change the shell used to execute the command.
|
||||
- This expects an absolute path to the executable.
|
||||
version_added: "0.9"
|
||||
warn:
|
||||
description:
|
||||
- if command warnings are on in ansible.cfg, do not warn about this particular line if set to no/false.
|
||||
- Enable or disable task warnings.
|
||||
type: bool
|
||||
default: 'yes'
|
||||
default: yes
|
||||
version_added: "1.8"
|
||||
stdin:
|
||||
version_added: "2.4"
|
||||
description:
|
||||
- Set the stdin of the command directly to the specified value.
|
||||
version_added: "2.4"
|
||||
notes:
|
||||
- If you want to execute a command securely and predictably, it may be
|
||||
better to use the M(command) module instead. Best practices when writing
|
||||
|
|
@ -68,15 +73,12 @@ notes:
|
|||
- To sanitize any variables passed to the shell module, you should use
|
||||
"{{ var | quote }}" instead of just "{{ var }}" to make sure they don't include evil things like semicolons.
|
||||
- For Windows targets, use the M(win_shell) module instead.
|
||||
- Rather than using here documents to create multi-line scripts inside playbooks,
|
||||
use the M(script) module instead.
|
||||
requirements: [ ]
|
||||
author:
|
||||
- Ansible Core Team
|
||||
- Michael DeHaan
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
EXAMPLES = r'''
|
||||
- name: Execute the command in remote shell; stdout goes to the specified file on the remote.
|
||||
shell: somescript.sh >> somelog.txt
|
||||
|
||||
|
|
@ -107,13 +109,13 @@ EXAMPLES = '''
|
|||
spawn ssh admin@{{ cimc_host }}
|
||||
|
||||
expect "password:"
|
||||
send "{{ cimc_password }}\\n"
|
||||
send "{{ cimc_password }}\n"
|
||||
|
||||
expect "\\n{{ cimc_name }}"
|
||||
send "connect host\\n"
|
||||
expect "\n{{ cimc_name }}"
|
||||
send "connect host\n"
|
||||
|
||||
expect "pxeboot.n12"
|
||||
send "\\n"
|
||||
send "\n"
|
||||
|
||||
exit 0
|
||||
args:
|
||||
|
|
@ -124,10 +126,10 @@ EXAMPLES = '''
|
|||
- name: Using curl to connect to a host via SOCKS proxy (unsupported in uri). Ordinarily this would throw a warning.
|
||||
shell: curl --socks5 localhost:9000 http://www.ansible.com
|
||||
args:
|
||||
warn: False
|
||||
warn: no
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
RETURN = r'''
|
||||
msg:
|
||||
description: changed
|
||||
returned: always
|
||||
|
|
|
|||
Loading…
Reference in a new issue