Merge pull request #1655 from jpmens/docs_jumbopatch

DOCUMENTATION strings
This commit is contained in:
Michael DeHaan 2012-11-21 16:08:17 -08:00
commit 8e515c0c94
38 changed files with 111 additions and 102 deletions

View file

@ -543,10 +543,12 @@ code, pre {
-moz-border-radius: 3px; -moz-border-radius: 3px;
border-radius: 3px; border-radius: 3px;
} }
.module {
font-family: Monaco, Andale Mono, Courier New, monospace;
font-size: 12px;
}
code { code {
background-color: #fee9cc;
color: rgba(0, 0, 0, 0.75); color: rgba(0, 0, 0, 0.75);
padding: 1px 3px;
} }
pre { pre {
background-color: #f5f5f5; background-color: #f5f5f5;

View file

@ -543,10 +543,12 @@ code, pre {
-moz-border-radius: 3px; -moz-border-radius: 3px;
border-radius: 3px; border-radius: 3px;
} }
.module {
font-family: Monaco, Andale Mono, Courier New, monospace;
font-size: 12px;
}
code { code {
background-color: #fee9cc;
color: rgba(0, 0, 0, 0.75); color: rgba(0, 0, 0, 0.75);
padding: 1px 3px;
} }
pre { pre {
background-color: #f5f5f5; background-color: #f5f5f5;

View file

@ -347,6 +347,13 @@ Include it in your module file like this::
description: Optional words describing this example description: Optional words describing this example
''' '''
The ``description``, ``notes`` and ``description`` within ``examples``
support formatting in some of the output formats (e.g. ``rst``, ``man``).
These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()``
for URL, module, italic, and constant-width respectively. It is suggested
to use ``C()`` for file and option names, and ``I()`` when referencing
parameters; module names should be specifies as ``M(module)``.
Building & Testing Building & Testing
++++++++++++++++++ ++++++++++++++++++

View file

@ -100,13 +100,9 @@ def rst_ify(text):
t = _ITALIC.sub(r'*' + r"\1" + r"*", text) t = _ITALIC.sub(r'*' + r"\1" + r"*", text)
t = _BOLD.sub(r'**' + r"\1" + r"**", t) t = _BOLD.sub(r'**' + r"\1" + r"**", t)
# mdehaan is disabling because he finds all the Sphinx orange distracting t = _MODULE.sub(r'``' + r"\1" + r"``", t)
#t = _MODULE.sub(r'``' + r"\1" + r"``", t)
t = _MODULE.sub(r"\1", t)
t = _URL.sub(r"\1", t) t = _URL.sub(r"\1", t)
# ditto t = _CONST.sub(r'``' + r"\1" + r"``", t)
# t = _CONST.sub(r'``' + r"\1" + r"``", t)
t = _CONST.sub(r"\1", t)
return t return t

View file

@ -24,7 +24,7 @@ DOCUMENTATION = '''
module: apt module: apt
short_description: Manages apt-packages short_description: Manages apt-packages
description: description:
- Manages apt-packages (such as for Debian/Ubuntu). - Manages I(apt) packages (such as for Debian/Ubuntu).
version_added: "0.0.2" version_added: "0.0.2"
options: options:
pkg: pkg:
@ -40,13 +40,13 @@ options:
choices: [ "latest", "absent", "present" ] choices: [ "latest", "absent", "present" ]
update_cache: update_cache:
description: description:
- Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as a seperate step - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as a separate step
required: false required: false
default: "no" default: "no"
choices: [ "yes", "no" ] choices: [ "yes", "no" ]
purge: purge:
description: description:
- Will force purging of configuration files if the module state is set to C(absent). - Will force purging of configuration files if the module state is set to I(absent).
required: false required: false
default: "no" default: "no"
choices: [ "yes", "no" ] choices: [ "yes", "no" ]
@ -81,7 +81,7 @@ examples:
- code: "apt: pkg=nginx state=latest default-release=squeeze-backports update-cache=yes" - code: "apt: pkg=nginx state=latest default-release=squeeze-backports update-cache=yes"
description: Update the repository cache and update package C(ngnix) to latest version using default release C(squeeze-backport) description: Update the repository cache and update package C(ngnix) to latest version using default release C(squeeze-backport)
- code: "apt: pkg=openjdk-6-jdk state=latest install-recommends=no" - code: "apt: pkg=openjdk-6-jdk state=latest install-recommends=no"
description: Install latest version of C(openjdk-6-jdk) ignoring C(install-recomands) description: Install latest version of C(openjdk-6-jdk) ignoring C(install-reccomends)
''' '''
import traceback import traceback

View file

@ -28,7 +28,7 @@ DOCUMENTATION = '''
module: apt_repository module: apt_repository
short_description: Manages apt repositores short_description: Manages apt repositores
description: description:
- Manages apt repositores (such as for Debian/Ubuntu). - Manages apt repositories (such as for Debian/Ubuntu).
version_added: "0.7" version_added: "0.7"
options: options:
repo: repo:
@ -43,7 +43,7 @@ options:
default: present default: present
choices: [ "present", "absent" ] choices: [ "present", "absent" ]
notes: notes:
- This module works on Debian and Ubuntu only and requires C(apt-add-repository) be available on destination server. To ensure this package is available use the C(apt) module and install the C(python-software-properties) package before using this module. - This module works on Debian and Ubuntu only and requires C(apt-add-repository) be available on the destination server. To ensure this package is available use the M(apt) module and install the C(python-software-properties) package before using this module.
- This module cannot be used on Debian Squeeze (Version 6) as there is no C(add-apt-repository) in C(python-software-properties) - This module cannot be used on Debian Squeeze (Version 6) as there is no C(add-apt-repository) in C(python-software-properties)
- A bug in C(apt-add-repository) always adds C(deb) and C(deb-src) types for repositories (see the issue on Launchpad U(https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264)), if a repo doesn't have source information (eg MongoDB repo from 10gen) the system will fail while updating repositories. - A bug in C(apt-add-repository) always adds C(deb) and C(deb-src) types for repositories (see the issue on Launchpad U(https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264)), if a repo doesn't have source information (eg MongoDB repo from 10gen) the system will fail while updating repositories.
author: Matt Wright author: Matt Wright

View file

@ -31,7 +31,7 @@ description:
- Assembles a configuration file from fragments. Often a particular - Assembles a configuration file from fragments. Often a particular
program will take a single configuration file and does not support a program will take a single configuration file and does not support a
C(conf.d) style structure where it is easy to build up the configuration C(conf.d) style structure where it is easy to build up the configuration
from multiple sources. Assemble will take a directory of files that have from multiple sources. M(assemble) will take a directory of files that have
already been transferred to the system, and concatenate them together to already been transferred to the system, and concatenate them together to
produce a destination file. Files are assembled in string sorting order. produce a destination file. Files are assembled in string sorting order.
Puppet calls this idea I(fragments). Puppet calls this idea I(fragments).

View file

@ -31,7 +31,7 @@ DOCUMENTATION = '''
module: command module: command
short_description: Executes a command on a remote node short_description: Executes a command on a remote node
description: description:
- The command module takes the command name followed by a list of space-delimited arguments. - The M(command) module takes the command name followed by a list of space-delimited arguments.
- The given command will be executed on all selected nodes. It will not be - The given command will be executed on all selected nodes. It will not be
processed through the shell, so variables like C($HOME) and operations processed through the shell, so variables like C($HOME) and operations
like C("<"), C(">"), C("|"), and C("&") will not work. As such, all like C("<"), C(">"), C("|"), and C("&") will not work. As such, all
@ -70,7 +70,7 @@ examples:
- code: "command: /sbin/shutdown -t now" - code: "command: /sbin/shutdown -t now"
description: "Example from Ansible Playbooks" description: "Example from Ansible Playbooks"
- code: "command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database" - code: "command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database"
description: "I(creates), I(removes), and I(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this." description: "C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this."
notes: notes:
- If you want to run a command through the shell (say you are using C(<), - 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. The C(>), C(|), etc), you actually want the M(shell) module instead. The

View file

@ -31,7 +31,7 @@ short_description: Manage crontab entries.
description: description:
- Use this module to manage crontab entries. This module allows you to create named - Use this module to manage crontab entries. This module allows you to create named
crontab entries, update, or delete them. crontab entries, update, or delete them.
- 'The module include one line with the description of the crontab entry "#Ansible: <name>" - 'The module includes one line with the description of the crontab entry C("#Ansible: <name>")
corresponding to the "name" passed to the module, which is used by future ansible/module calls corresponding to the "name" passed to the module, which is used by future ansible/module calls
to find/check the state.' to find/check the state.'
version_added: "0.9" version_added: "0.9"
@ -64,7 +64,7 @@ options:
backup: backup:
description: description:
- If set, then create a backup of the crontab before it is modified. - If set, then create a backup of the crontab before it is modified.
- The location of the backup is returned in the 'backup' variable by this module. - The location of the backup is returned in the C(backup) variable by this module.
required: false required: false
default: false default: false
aliases: [] aliases: []

View file

@ -28,12 +28,12 @@ description:
the playbook. Useful for debugging together with the only_if directive. the playbook. Useful for debugging together with the only_if directive.
In order to see the debug message, you need to run ansible in verbose In order to see the debug message, you need to run ansible in verbose
mode (using the -v option). mode (using the C(-v) option).
version_added: "0.8" version_added: "0.8"
options: options:
msg: msg:
description: description:
- The customized message that is printed. If ommited, prints a generic - The customized message that is printed. If omitted, prints a generic
message. message.
required: false required: false
default: "Hello world!" default: "Hello world!"

View file

@ -19,12 +19,12 @@ DOCUMENTATION = '''
module: ec2 module: ec2
short_description: create an instance in ec2, return instanceid short_description: create an instance in ec2, return instanceid
description: description:
- creates ec2 instances and optionally waits for it to be 'running'. This module has a dependency on the external euca2ools package. - creates ec2 instances and optionally waits for it to be 'running'. This module has a dependency on the external I(euca2ools) package.
version_added: "0.9" version_added: "0.9"
options: options:
keypair: keypair:
description: description:
- keypair to use on the instance - key pair to use on the instance
required: true required: true
default: null default: null
aliases: [] aliases: []
@ -42,19 +42,19 @@ options:
aliases: [] aliases: []
image: image:
description: description:
- emi (or ami) to use for the instance - I(emi) (or I(ami)) to use for the instance
required: true required: true
default: null default: null
aliases: [] aliases: []
kernel: kernel:
description: description:
- kernel eki to use for the instance - kernel I(eki) to use for the instance
required: false required: false
default: null default: null
aliases: [] aliases: []
ramdisk: ramdisk:
description: description:
- ramdisk eri to use for the instance - ramdisk I(eri) to use for the instance
required: false required: false
default: null default: null
aliases: [] aliases: []
@ -66,7 +66,7 @@ options:
aliases: [] aliases: []
ec2_url: ec2_url:
description: description:
- url to use to connect to ec2 or your cloud (for example https://ec2.amazonaws.com when using Amazon ec2 directly and not Eucalyptus) - url to use to connect to ec2 or your cloud (for example U(https://ec2.amazonaws.com) when using Amazon ec2 directly and not Eucalyptus)
required: False required: False
default: null default: null
aliases: [] aliases: []

View file

@ -24,12 +24,12 @@ module: fail
short_description: Fail with custom message short_description: Fail with custom message
description: description:
- This module fails the progress with a custom message. It can be - This module fails the progress with a custom message. It can be
useful for bailing out when a certain condition is met using only_if. useful for bailing out when a certain condition is met using C(only_if).
version_added: "0.8" version_added: "0.8"
options: options:
msg: msg:
description: description:
- The customized message used for failing execution. If ommited, - The customized message used for failing execution. If omitted,
fail will simple bail out with a generic message. fail will simple bail out with a generic message.
required: false required: false
default: "'Failed as requested from task'" default: "'Failed as requested from task'"

View file

@ -12,7 +12,7 @@ version_added: "0.2"
options: options:
src: src:
description: description:
- The file on the remote system to fetch. This must be a file, not a - The file on the remote system to fetch. This I(must) be a file, not a
directory. Recursive fetching may be supported in a later release. directory. Recursive fetching may be supported in a later release.
required: true required: true
default: null default: null
@ -20,7 +20,7 @@ options:
dest: dest:
description: description:
- A directory to save the file into. For example, if the I(dest) - A directory to save the file into. For example, if the I(dest)
directory is C(/backup) a src file named C(/etc/profile) on host directory is C(/backup) a I(src) file named C(/etc/profile) on host
C(host.example.com), would be saved into C(host.example.com), would be saved into
C(/backup/host.example.com/etc/profile) C(/backup/host.example.com/etc/profile)
required: true required: true

View file

@ -35,11 +35,11 @@ short_description: Sets attributes of files
description: description:
- Sets attributes of files, symlinks, and directories, or removes - Sets attributes of files, symlinks, and directories, or removes
files/symlinks/directories. Many other modules support the same options as files/symlinks/directories. Many other modules support the same options as
the file module - including M(copy), M(template), and M(assmeble). the file module - including M(copy), M(template), and M(assemble).
options: options:
path: path:
description: 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) - defines the file being managed, unless when used with C(state=link), and then sets the destination to create a symbolic link to using I(src)
required: true required: true
default: [] default: []
aliases: [] aliases: []
@ -59,7 +59,7 @@ options:
default: null default: null
choices: [] choices: []
description: description:
- mode the file or directory should be, such as 0644 as would be fed to - mode the file or directory should be, such as 0644 as would be fed to I(chmod)
owner: owner:
required: false required: false
default: null default: null
@ -85,7 +85,7 @@ options:
description: description:
- user part of SELinux file context. Will default to system policy, if - user part of SELinux file context. Will default to system policy, if
applicable. If set to C(_default), it will use the C(user) portion of the applicable. If set to C(_default), it will use the C(user) portion of the
the policy if available policy if available
serole: serole:
required: false required: false
default: null default: null

View file

@ -24,7 +24,7 @@ module: fireball
short_description: Enable fireball mode on remote node short_description: Enable fireball mode on remote node
description: description:
- This modules launches an ephemeral I(fireball) ZeroMQ message bus daemon on the remote node which - This modules launches an ephemeral I(fireball) ZeroMQ message bus daemon on the remote node which
Ansible can to communicate with nodes at high speed. Ansible can use to communicate with nodes at high speed.
- The daemon listens on a configurable port for a configurable amount of time. - The daemon listens on a configurable port for a configurable amount of time.
- Starting a new fireball as a given user terminates any existing user fireballs. - Starting a new fireball as a given user terminates any existing user fireballs.
- Fireball mode is AES encrypted - Fireball mode is AES encrypted

View file

@ -30,7 +30,7 @@ module: get_url
short_description: Downloads files from HTTP, HTTPS, or FTP to node short_description: Downloads files from HTTP, HTTPS, or FTP to node
description: description:
- Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote - Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote
server must have direct access to the remote resource. server I(must) have direct access to the remote resource.
version_added: "0.6" version_added: "0.6"
options: options:
url: url:
@ -42,13 +42,13 @@ options:
dest: dest:
description: description:
- absolute path of where to download the file to. - 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. - If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, C(thirsty=yes) must also be set.
required: true required: true
default: null default: null
thirsty: thirsty:
description: description:
- if C(yes), will download the file every time and replace the - 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 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 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. local files. prior to 0.6, acts if C(yes) by default.
version_added: "0.7" version_added: "0.7"

View file

@ -25,13 +25,13 @@ author: Michael DeHaan
version_added: 0.0.1 version_added: 0.0.1
short_description: Deploy software (or files) from git checkouts short_description: Deploy software (or files) from git checkouts
description: description:
- Manage git checkouts of repositories to deploy files or software. - Manage I(git) checkouts of repositories to deploy files or software.
options: options:
repo: repo:
required: true required: true
aliases: [ name ] aliases: [ name ]
description: description:
- git, ssh, or http protocol address of the git repository. - git, SSH, or HTTP protocol address of the git repository.
dest: dest:
required: true required: true
description: description:
@ -41,7 +41,7 @@ options:
default: "HEAD" default: "HEAD"
description: description:
- What version of the repository to check out. This can be the - What version of the repository to check out. This can be the
git I(SHA), the literal string I(HEAD), branch name, or a tag name. git I(SHA), the literal string C(HEAD), a branch name, or a tag name.
remote: remote:
required: false required: false
default: "origin" default: "origin"
@ -51,8 +51,9 @@ options:
required: false required: false
default: "yes" default: "yes"
choices: [ yes, no ] choices: [ yes, no ]
version_added: "0.7"
description: description:
- (New in 0.7) If yes, any modified files in the working - If C(yes), any modified files in the working
repository will be discarded. Prior to 0.7, this was always repository will be discarded. Prior to 0.7, this was always
'yes' and could not be disabled. 'yes' and could not be disabled.
examples: examples:

View file

@ -54,7 +54,7 @@ options:
required: false required: false
description: description:
- Required for C(state=present). The line to insert/replace into the - Required for C(state=present). The line to insert/replace into the
file. Must match the value given to C(regexp). file. Must match the value given to I(regexp).
insertafter: insertafter:
required: false required: false
default: EOF default: EOF

View file

@ -65,18 +65,18 @@ options:
default: null default: null
target: target:
description: description:
- Where to dump/get the .sql file - Where to dump/get the C(.sql) file
required: true required: true
examples: examples:
- code: "mysql_db: db=bobdata state=present" - code: "mysql_db: db=bobdata state=present"
description: Create a new database with name 'bobdata' description: Create a new database with name 'bobdata'
notes: notes:
- Requires the MySQLdb Python package on the remote host. For Ubuntu, this - Requires the MySQLdb Python package on the remote host. For Ubuntu, this
is as easy as apt-get install python-mysqldb. is as easy as apt-get install python-mysqldb. (See M(apt).)
- Both C(login_password) and C(login_username) are required when you are - Both I(login_password) and I(login_username) are required when you are
passing credentials. If none are present, the module will attempt to read passing credentials. If none are present, the module will attempt to read
the credentials from C(~/.my.cnf), and finally fall back to using the MySQL the credentials from C(~/.my.cnf), and finally fall back to using the MySQL
default login of 'root' with no password. default login of C(root) with no password.
requirements: [ ConfigParser ] requirements: [ ConfigParser ]
author: Mark Theunissen author: Mark Theunissen
''' '''

View file

@ -21,10 +21,10 @@ module: nagios
short_description: Perform common tasks in Nagios related to downtime and notifications. short_description: Perform common tasks in Nagios related to downtime and notifications.
description: description:
- "The M(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts." - "The M(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts."
- All actions require the C(host) parameter to be given explicitly. In playbooks you can use the C($inventory_hostname) variable to refer to the host the playbook is currently running on. - All actions require the I(host) parameter to be given explicitly. In playbooks you can use the C($inventory_hostname) variable to refer to the host the playbook is currently running on.
- You can specify multiple services at once by separating them with commas, .e.g., C(services=httpd,nfs,puppet). - You can specify multiple services at once by separating them with commas, .e.g., C(services=httpd,nfs,puppet).
- When specifying what service to handle there is a special service value, I(host), which will handle alerts/downtime for the I(host itself), e.g., C(service=host). This keyword may not be given with other services at the same time. I(Setting alerts/downtime for a host does not affect alerts/downtime for any of the services running on it.) - When specifying what service to handle there is a special service value, I(host), which will handle alerts/downtime for the I(host itself), e.g., C(service=host). This keyword may not be given with other services at the same time. I(Setting alerts/downtime for a host does not affect alerts/downtime for any of the services running on it.)
- When using the M(nagios) module you will need to specify your nagios server using the C(delegate_to) parameter. - When using the M(nagios) module you will need to specify your Nagios server using the C(delegate_to) parameter.
version_added: 0.7 version_added: 0.7
options: options:
action: action:
@ -47,13 +47,13 @@ options:
author: author:
description: description:
- Author to leave downtime comments as. - Author to leave downtime comments as.
- Only useable with the C(downtime) action. - Only usable with the C(downtime) action.
required: false required: false
default: Ansible default: Ansible
minutes: minutes:
description: description:
- Minutes to schedule downtime for. - Minutes to schedule downtime for.
- Only useable with the C(downtime) action. - Only usable with the C(downtime) action.
required: false required: false
default: 30 default: 30
services: services:

View file

@ -22,9 +22,9 @@
DOCUMENTATION = ''' DOCUMENTATION = '''
--- ---
module: ohai module: ohai
short_description: Returns inventory data from I(ohai) short_description: Returns inventory data from I(Ohai)
description: description:
- Similar to the M(facter) module, this runs the I(ohai) discovery program - Similar to the M(facter) module, this runs the I(Ohai) discovery program
(U(http://wiki.opscode.com/display/chef/Ohai)) on the remote host and (U(http://wiki.opscode.com/display/chef/Ohai)) on the remote host and
returns JSON inventory data. returns JSON inventory data.
I(Ohai) data is a bit more verbose and nested than I(facter). I(Ohai) data is a bit more verbose and nested than I(facter).

View file

@ -22,10 +22,10 @@
DOCUMENTATION = ''' DOCUMENTATION = '''
--- ---
module: ping module: ping
short_description: Try to connect to host and return pong on success. short_description: Try to connect to host and return C(pong) on success.
description: description:
- A trivial test module, this module always returns 'pong' on successful - A trivial test module, this module always returns C(pong) on successful
contact. It does not make sense in playbooks, but is useful from contact. It does not make sense in playbooks, but it is useful from
C(/usr/bin/ansible) C(/usr/bin/ansible)
options: {} options: {}
examples: examples:

View file

@ -34,7 +34,7 @@ options:
default: null default: null
version: version:
description: description:
- The version number to install of the Python library specified in the 'name' parameter - The version number to install of the Python library specified in the I(name) parameter
required: false required: false
default: null default: null
requirements: requirements:
@ -44,7 +44,7 @@ options:
default: null default: null
virtualenv: virtualenv:
description: description:
- An optional path to a virtualenv directory to install into - An optional path to a I(virtualenv) directory to install into
required: false required: false
default: null default: null
state: state:
@ -63,7 +63,7 @@ examples:
- code: "pip: requirements=/srv/webapps/my_app/src/requirements.txt" - code: "pip: requirements=/srv/webapps/my_app/src/requirements.txt"
description: Install specified python requirements. description: Install specified python requirements.
- code: "pip: requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv" - code: "pip: requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv"
description: Install specified python requirements in indicated virtualenv. description: Install specified python requirements in indicated I(virtualenv).
notes: notes:
- Please note that U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified. - Please note that U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified.
requirements: [ "virtualenv", "pip" ] requirements: [ "virtualenv", "pip" ]

View file

@ -57,10 +57,11 @@ options:
choices: [ "present", "absent" ] choices: [ "present", "absent" ]
examples: examples:
- code: "postgresql_db: db=acme" - code: "postgresql_db: db=acme"
description: Create a new database with name 'acme' description: Create a new database with name C(acme)
notes: notes:
- The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host. - The default authentication assumes that you are either logging in as or sudo'ing to the C(postgres) account on the host.
- This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module. - This module uses I(psycopg2), a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on
the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the C(postgresql), C(libpq-dev), and C(python-psycopg2) packages on the remote host before using this module.
requirements: [ psycopg2 ] requirements: [ psycopg2 ]
author: Lorin Hochstein author: Lorin Hochstein
''' '''

View file

@ -28,7 +28,7 @@ description:
step, which works on one database at a time. This allows for the module to step, which works on one database at a time. This allows for the module to
be called several times in the same module to modify the permissions on be called several times in the same module to modify the permissions on
different databases, or to grant permissions to already existing users. different databases, or to grant permissions to already existing users.
- A user cannot be removed untill all the privileges have been stripped from - A user cannot be removed until all the privileges have been stripped from
the user. In such situation, if the module tries to remove the user it the user. In such situation, if the module tries to remove the user it
will fail. To avoid this from happening the fail_on_user option signals will fail. To avoid this from happening the fail_on_user option signals
the module to try to remove the user, but if not possible keep going; the the module to try to remove the user, but if not possible keep going; the
@ -53,7 +53,7 @@ options:
default: null default: null
fail_on_user: fail_on_user:
description: description:
- if yes, fail when user can't be removed. Otherwise just log and continue - if C(yes), fail when user can't be removed. Otherwise just log and continue
required: false required: false
default: yes default: yes
choices: [ "yes", "no" ] choices: [ "yes", "no" ]

View file

@ -8,7 +8,7 @@ options: {}
description: description:
- Executes a low-down and dirty SSH command, not going through the module - 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 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 first case is installing C(python-simplejson) on older (Python 2.4 and
before) hosts that need it as a dependency to run modules, since nearly 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 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 routers that do not have any Python installed. In any other case, using
@ -18,6 +18,6 @@ description:
support for this module support for this module
examples: examples:
- code: ansible newhost.example.com -m raw -a "yum -y install python-simplejson" - 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 description: Example from C(/usr/bin/ansible) to bootstrap a legacy python 2.4 host
author: Michael DeHaan author: Michael DeHaan
''' '''

View file

@ -17,7 +17,7 @@ examples:
- description: "Example from Ansible Playbooks" - description: "Example from Ansible Playbooks"
code: "script: /some/local/script.sh --some-arguments 1234" code: "script: /some/local/script.sh --some-arguments 1234"
notes: notes:
- It is preferable to write Ansible modules than pushing scripts. Convert your script to an ansible module for bonus points! - It is preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
author: Michael DeHaan author: Michael DeHaan
""" """

View file

@ -32,7 +32,7 @@ options:
default: null default: null
persistent: persistent:
description: description:
- Set to 'yes' if the boolean setting should survive a reboot - Set to C(yes) if the boolean setting should survive a reboot
required: false required: false
default: no default: no
choices: [ "yes", "no" ] choices: [ "yes", "no" ]

View file

@ -28,7 +28,7 @@ version_added: "0.7"
options: options:
policy: policy:
description: description:
- "name of the SELinux policy to use (example: 'targeted') will be required if state is not 'disabled'" - "name of the SELinux policy to use (example: C(targeted)) will be required if state is not C(disabled)"
required: false required: false
default: null default: null
state: state:

View file

@ -35,10 +35,9 @@ options:
required: false required: false
choices: [ started, stopped, restarted, reloaded ] choices: [ started, stopped, restarted, reloaded ]
description: description:
- I(started), I(stopped), I(reloaded), I(restarted). C(Started)/C(stopped) are idempotent actions that will not run
I(Started)/I(stopped) are idempotent actions that will not run commands unless necessary. C(restarted) will always bounce the
commands unless necessary. I(restarted) will always bounce the service. C(reloaded) will always reload.
service. I(reloaded) will always reload.
pattern: pattern:
required: false required: false
version_added: "0.7" version_added: "0.7"

View file

@ -44,10 +44,10 @@ notes:
with C(facter_) and C(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 bubbled up to the caller. Using the ansible facts and choosing to not
install I(facter) and I(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. remote systems. (See also M(facter) and M(ohai).)
examples: examples:
- code: ansible all -m setup --tree /tmp/facts - code: ansible all -m setup --tree /tmp/facts
description: Obtain facts from all hosts and store them indexed by hostname at /tmp/facts. description: Obtain facts from all hosts and store them indexed by I(hostname) at C(/tmp/facts).
author: Michael DeHaan author: Michael DeHaan
''' '''

View file

@ -24,9 +24,10 @@ options:
default: null default: null
chdir: chdir:
description: description:
- cd into this directory before running the command (0.6 and later) - cd into this directory before running the command
required: false required: false
default: null default: null
version_added: "0.6"
executable: executable:
description: 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. Should be an absolute path to the executable.
@ -37,7 +38,7 @@ examples:
- code: "shell: somescript.sh >> somelog.txt" - code: "shell: somescript.sh >> somelog.txt"
description: Execute the command in remote shell description: Execute the command in remote shell
notes: notes:
- If you want to execute a command securely and predicably, it may be - 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 better to use the M(command) module instead. Best practices when writing
playbooks will follow the trend of using M(command) unless M(shell) is playbooks will follow the trend of using M(command) unless M(shell) is
explicitly required. When running ad-hoc commands, use your best explicitly required. When running ad-hoc commands, use your best

View file

@ -28,7 +28,7 @@ description:
options: options:
src: src:
description: description:
- The file on the remote system to fetch. This must be a file, not a - The file on the remote system to fetch. This I(must) be a file, not a
directory. directory.
required: true required: true
default: null default: null

View file

@ -38,7 +38,7 @@ options:
default: null default: null
force: force:
description: description:
- If yes, any modified files in the working repository will be discarded. If no, this module will fail if it encounters modified files. - If C(yes), any modified files in the working repository will be discarded. If C(no), this module will fail if it encounters modified files.
required: false required: false
default: yes default: yes
choices: [ "yes", "no" ] choices: [ "yes", "no" ]
@ -46,7 +46,7 @@ examples:
- code: "subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout" - code: "subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout"
description: Export subversion repository in a specified folder description: Export subversion repository in a specified folder
notes: notes:
- Requires subversion and grep on the client. - Requires I(subversion) and I(grep) on the client.
requirements: [ ] requirements: [ ]
author: Dane Summers author: Dane Summers
''' '''

View file

@ -24,12 +24,12 @@ DOCUMENTATION = '''
module: supervisorctl module: supervisorctl
short_description: Manage the state of a program or group of programs running via Supervisord short_description: Manage the state of a program or group of programs running via Supervisord
description: description:
- Manage the state of a program or group of programs running via Supervisord - Manage the state of a program or group of programs running via I(Supervisord)
version_added: "0.7" version_added: "0.7"
options: options:
name: name:
description: description:
- The name of the supervisord program/process to manage - The name of the I(supervisord) program/process to manage
required: true required: true
default: null default: null
state: state:

View file

@ -40,7 +40,7 @@ options:
state: state:
description: description:
- Whether to install (C(present)), or remove (C(absent)) a package. - Whether to install (C(present)), or remove (C(absent)) a package.
- If the package is to be installed, then C(src) is required. - If the package is to be installed, then I(src) is required.
- The SVR4 package system doesn't provide an upgrade operation. You need to uninstall the old, then install the new package. - The SVR4 package system doesn't provide an upgrade operation. You need to uninstall the old, then install the new package.
required: true required: true
choices: ["present", "absent"] choices: ["present", "absent"]
@ -49,7 +49,7 @@ options:
description: description:
- Specifies the location to install the package from. Required when C(state=present). - Specifies the location to install the package from. Required when C(state=present).
- "Can be any path acceptable to the C(pkgadd) command's C(-d) option. e.g.: C(somefile.pkg), C(/dir/with/pkgs), C(http:/server/mypkgs.pkg)." - "Can be any path acceptable to the C(pkgadd) command's C(-d) option. e.g.: C(somefile.pkg), C(/dir/with/pkgs), C(http:/server/mypkgs.pkg)."
- If using a file or directory, they must already be accessible by the host. See the I(copy) module for a way to get them there. - If using a file or directory, they must already be accessible by the host. See the M(copy) module for a way to get them there.
proxy: proxy:
description: description:
- HTTP[s] proxy to be used if C(src) is a URL. - HTTP[s] proxy to be used if C(src) is a URL.

View file

@ -52,7 +52,7 @@ options:
append: append:
required: false required: false
description: description:
- If I(yes), will only add groups, not set them to just the list - If C(yes), will only add groups, not set them to just the list
in I(groups). in I(groups).
shell: shell:
required: false required: false
@ -73,36 +73,36 @@ options:
default: "present" default: "present"
choices: [ present, absent ] choices: [ present, absent ]
description: description:
- Whether the account should exist. When I(absent), removes - Whether the account should exist. When C(absent), removes
the user account. the user account.
createhome: createhome:
required: false required: false
default: "yes" default: "yes"
choices: [ yes, no ] choices: [ yes, no ]
description: description:
- Unless set to I(no), a home directory will be made for the user - Unless set to C(no), a home directory will be made for the user
when the account is created. when the account is created.
system: system:
required: false required: false
default: "no" default: "no"
choices: [ yes, no ] choices: [ yes, no ]
description: description:
- When creating an account, setting this to I(yes) makes the user a - When creating an account, setting this to C(yes) makes the user a
system account. This setting cannot be changed on existing users. system account. This setting cannot be changed on existing users.
force: force:
required: false required: false
default: "no" default: "no"
choices: [ yes, no ] choices: [ yes, no ]
description: description:
- When used with I(state=absent), behavior is as with - When used with C(state=absent), behavior is as with
I(userdel --force). C(userdel --force).
remove: remove:
required: false required: false
default: "no" default: "no"
choices: [ yes, no ] choices: [ yes, no ]
description: description:
- When used with I(state=absent), behavior is as with - When used with C(state=absent), behavior is as with
I(userdel --remove). C(userdel --remove).
generate_ssh_key: generate_ssh_key:
required: false required: false
default: "no" default: "no"

View file

@ -61,7 +61,7 @@ options:
disablerepo: disablerepo:
description: description:
- Repoid of repositories to disable for the install/update operation - I(repoid) of repositories to disable for the install/update operation
These repos will not persist beyond the transaction These repos will not persist beyond the transaction
Multiple repos separated with a ',' Multiple repos separated with a ','
New in version 0.9. New in version 0.9.