Tweak DOCUMENTATION YAML as per latest 991

This commit is contained in:
Jan-Piet Mens 2012-09-19 16:09:26 +02:00
parent 9146fc74e1
commit af1f925eea
4 changed files with 77 additions and 40 deletions

33
file
View file

@ -28,6 +28,39 @@ try:
except ImportError:
HAVE_SELINUX=False
DOCUMENTATION = '''
---
module: file
short_description: Sets attributes of files
description:
- Sets attributes of files, symlinks, and directories, or removes
files/symlinks/directories. Many other modules support the same options as
the file module - including M(copy), M(template), and M(assmeble).
version_added: "0.1"
options:
- dest:
description:
- defines the file being managed, unless when used with I(state=link), and then sets the destination to create a symbolic link to using I(src)
required: true
default: []
aliases: []
- state:
description:
- If directory, all immediate subdirectories will be created if they do not exist. If I(file), the file will NOT be created if it does not exist, see the M(copy) or M(template) module if you want that behavior. If I(link), the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked.
required: false
default: file
choices: [ file, link, directory, absent ]
- mode:
description:
- mode the file or directory should be, such as 0644 as would be fed to I(chmod). English modes like B(g+x) are not yet supported
examples:
- code: file path=/etc/foo.conf owner=foo group=foo mode=0644
description: Example from Ansible Playbooks
notes:
- See also M(copy), M(template), M(assemble)
requirements: [ ]
'''
def add_path_info(kwargs):
path = kwargs['path']
if os.path.exists(path):

30
get_url
View file

@ -28,39 +28,43 @@ DOCUMENTATION = '''
---
module: get_url
short_description: Downloads files from HTTP, HTTPS, or FTP to node
description: >
Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote
description:
- Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote
server must have direct access to the remote resource.
version_added: "0.6"
options:
- url:
description: HTTP, HTTPS, or FTP URL
description:
- HTTP, HTTPS, or FTP URL
required: true
default: null
aliases: []
- dest:
description: absolute path of where to download the file to. If dest is a
directory, the basename of the file on the remote server will be used. If
a directory, thirsty=yes must also be set.
description:
- absolute path of where to download the file to.
- If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, I(thirsty=yes) must also be set.
required: true
default: null
- thirsty:
description: if yes, will download the file every time and replace the
file if the contents change. if no, the file will only be downloaded if
the destination does not exist. Generally should be 'yes' only for small
local files. prior to 0.6, acts if 'yes' by default.
description:
- if C(yes), will download the file every time and replace the
file if the contents change. if C(no), the file will only be downloaded if
the destination does not exist. Generally should be C(yes) only for small
local files. prior to 0.6, acts if C(yes) by default.
version_added: "0.7"
required: false
choices: [ "yes", "no" ]
default: "no"
- others:
description: all arguments accepted by the file module also work here
description:
- all arguments accepted by the M(file) module also work here
required: false
examples:
- code: get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
description: Obtain and install config file
notes: >
This module doesn't support proxies or passwords.
notes:
- This module doesn't support proxies or passwords.
- Also see the M(template) module.
# informational: requirements for nodes
requirements: [ urllib2, urlparse ]
'''

24
raw
View file

@ -3,18 +3,18 @@
DOCUMENTATION = '''
---
module: raw
short_description: Executes a low-down and dirty SSH command, not going through the module subsystem.
description: >
Executes a low-down and dirty SSH command, not going through the module
subsystem. This is useful and should only be done in two cases. The first
case is installing python-simplejson on older (python 2.4 and before)
hosts that need it as a dependency to run modules, since nearly all core
modules require it. Another is speaking to any devices such as routers
that do not have any Python installed. In any other case, using the
'shell' or 'command' module is much more appropriate. Arguments given to
'raw' are run directly through the configured remote shell and only output
is returned. There is no error detection or change handler support for
this module
short_description: Executes a low-down and dirty SSH command
description:
- Executes a low-down and dirty SSH command, not going through the module
subsystem. This is useful and should only be done in two cases. The
first case is installing python-simplejson on older (Python 2.4 and
before) hosts that need it as a dependency to run modules, since nearly
all core modules require it. Another is speaking to any devices such as
routers that do not have any Python installed. In any other case, using
the M(shell) or M(command) module is much more appropriate. Arguments
given to M(raw) are run directly through the configured remote shell and
only output is returned. There is no error detection or change handler
support for this module
examples:
- code: ansible newhost.example.com -m raw -a "yum -y install python-simplejson"
description: Example from /usr/bin/ansible to bootstrap a legacy python 2.4 host

18
setup
View file

@ -30,19 +30,19 @@ DOCUMENTATION = '''
---
module: setup
short_description: Gathers facts about remote hosts
description: >
This module is automatically called by playbooks to gather useful
description:
- This module is automatically called by playbooks to gather useful
variables about remote hosts that can be used in playbooks. It can also be
executed directly by /usr/bin/ansible to check what variables are
available to a host. Ansible provides many 'facts' about the system,
executed directly by C(/usr/bin/ansible) to check what variables are
available to a host. Ansible provides many I(facts) about the system,
automatically.
notes: >
More ansible facts will be added with successive releases. If facter or
ohai are installed, variables from these programs will also be snapshotted
notes:
- More ansible facts will be added with successive releases. If I(facter) or
I(ohai) are installed, variables from these programs will also be snapshotted
into the JSON file for usage in templating. These variables are prefixed
with facter_ and ohai_ so it's easy to tell their source. All variables are
with C(facter_) and C(ohai_) so it's easy to tell their source. All variables are
bubbled up to the caller. Using the ansible facts and choosing to not
install facter and ohai means you can avoid ruby-dependencies on your
install I(facter) and I(ohai) means you can avoid Ruby-dependencies on your
remote systems.
examples:
- code: ansible all -m setup -tree /tmp/facts