Merge pull request #1155 from jpmens/m-docs4

DOCUMENTATION for fetch,mount,ohai,easy_install; .rst template tweaks
reviewable/pr18780/r1
Michael DeHaan 12 years ago
commit 4b911a237c

@ -19,6 +19,42 @@
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
# #
DOCUMENTATION = '''
---
module: easy_install
short_description: Installs Python libraries
description:
- Installs Python libraries, optionally in a I(virtualenv)
version_added: "0.7"
options:
name:
description:
- A Python library name
required: true
default: null
aliases: []
virtualenv:
description:
- an optional I(virtualenv) directory path to install into. If the
I(virtualenv) does not exist, it is created automatically
required: false
default: null
examples:
- code: easy_install name=pip
description: "Examples from Ansible Playbooks"
- code: easy_install name=flask virtualenv=/webapps/myapp/venv
description: "Install I(flask) into the specified I(virtualenv)"
notes:
- Please note that the M(easy_install) command can only install Python
libraries. Thus this module is not able to remove libraries. It is
generally recommended to use the M(pip) module which you can first install
using M(easy_install).
- Also note that I(virtualenv) must be installed on the remote host if the
C(virtualenv) parameter is specified.
requirements: [ "virtualenv" ]
author: Matt Wright
'''
def _ensure_virtualenv(env, virtualenv): def _ensure_virtualenv(env, virtualenv):
if os.path.exists(os.path.join(env, 'bin', 'activate')): if os.path.exists(os.path.join(env, 'bin', 'activate')):
return 0, '', '' return 0, '', ''

@ -19,9 +19,23 @@
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
# #
# things that must be installed to use this
# facter DOCUMENTATION = '''
# ruby-json ---
module: facter
short_description: Runs the discovery program facter on the remote system
description:
- Runs the discovery program I(facter) on the remote system, returning JSON
data that can be useful for inventory purposes.
version_added: "0.2"
options: []
examples:
- code: ansible www.example.net -m facter
description: "Example command-line invocation"
notes: []
requirements: [ "facter", "ruby-json" ]
author: Michael DeHaan
'''
import subprocess import subprocess

34
fetch

@ -1 +1,35 @@
# this is a virtual module that is entirely implemented server side # this is a virtual module that is entirely implemented server side
DOCUMENTATION = '''
---
module: fetch
short_description: Fetches a file from remote nodes
description:
- This module works like M(copy), but in reverse. It is used for fetching
files from remote machines and storing them locally in a file tree,
organized by hostname.
version_added: "0.2"
options:
src:
description:
- The file on the remote system to fetch. This must be a file, not a
directory. Recursive fetching may be supported in a later release.
required: true
default: null
aliases: []
dest:
description:
- 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
C(host.example.com), would be saved into
C(/backup/host.example.com/etc/profile)
required: true
default: null
examples:
- code: fetch src=/var/log/messages dest=/home/logtree
description: "Example from Ansible Playbooks"
notes:
- "See also: M(copy)"
requirements: []
author: Michael DeHaan
'''

65
mount

@ -20,16 +20,61 @@
# You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
# mount module - mount fs and define in fstab DOCUMENTATION = '''
# usage: ---
# module: mount
# mount name=mountpoint, src=device_to_be_mounted fstype=fstype short_description: Control active and configured mount points
# opts=mount_opts, dump=0 passno=0 state=[present|absent|mounted|unmounted] description:
# - This module controls active and configured mount points in C(/etc/fstab).
# absent == remove from fstab and unmounted version_added: "0.6"
# present == add to fstab, do not change mount state options:
# mounted == add to fstab if not there and make sure it is mounted name:
# unmounted == do not change fstab state, but unmount description:
- "path to the mount point, eg: C(/mnt/files)"
required: true
default: null
aliases: []
src:
description:
- device to be mounted on I(name).
required: true
default: null
fstype:
description:
- file-system type
required: true
default: null
opts:
description:
- mount options (see fstab(8))
required: false
default: null
dump:
description:
- dump (see fstab(8))
required: false
default: null
passno:
description:
- passno (see fstab(8))
required: false
default: null
state:
description:
- If C(mounted) or C(unmounted), the device will be actively mounted or unmounted
as well as just configured in I(fstab). C(absent) and C(present) only deal with
I(fstab).
required: true
choices: [ "present", "absent", "mounted", "unmounted" ]
default: null
examples:
- code: mount name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro
description: "Mount DVD read-only"
notes: []
requirements: []
author: Seth Vidal
'''
def write_fstab(lines, dest): def write_fstab(lines, dest):

@ -58,7 +58,7 @@ options:
default: localhost default: localhost
priv: priv:
description: description:
- MySQL privileges string in the format: db.table:priv1,priv2 - "MySQL privileges string in the format: C(db.table:priv1,priv2)"
required: false required: false
default: null default: null
state: state:

17
ohai

@ -19,6 +19,23 @@
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
# #
DOCUMENTATION = '''
---
module: ohai
short_description: Returns inventory data from I(ohai)
description:
- Similar to the M(facter) module, this returns JSON inventory data.
I(Ohai) data is a bit more verbose and nested than I(facter).
version_added: "0.6"
options: []
examples:
- code: ansible webservers -m ohai --tree=/tmp/ohaidata
description: "Retrieve I(ohai) data from all Web servers and store in one-file per host"
notes: []
requirements: [ "ohai" ]
author: Michael DeHaan
'''
def get_ohai_data(): def get_ohai_data():
p = subprocess.Popen(["/usr/bin/env", "ohai"], stdout=subprocess.PIPE, stderr=subprocess.PIPE) p = subprocess.Popen(["/usr/bin/env", "ohai"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
(out, err) = p.communicate() (out, err) = p.communicate()

@ -21,9 +21,19 @@ DOCUMENTATION = '''
module: postgresql_user module: postgresql_user
short_description: Adds or removes a users (roles) from a PostgreSQL database. short_description: Adds or removes a users (roles) from a PostgreSQL database.
description: description:
- Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users access to an existing database or tables. - Add or remove PostgreSQL users (roles) from a remote host and, optionally,
- The fundamental function of the module is to create, or delete, roles from a PostgreSQL cluster. Privilege assignment, or removal, is an optional 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 different databases, or to grant permissions to already existing users. grant the users access to an existing database or tables.
- A user cannot be removed untill all the privileges have been stripped from 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 the module to try to remove the user, but if not possible keep going; the module will report if changes happened and separately if the user was removed or not. - The fundamental function of the module is to create, or delete, roles from
a PostgreSQL cluster. Privilege assignment, or removal, is an optional
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
different databases, or to grant permissions to already existing users.
- A user cannot be removed untill all the privileges have been stripped from
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
the module to try to remove the user, but if not possible keep going; the
module will report if changes happened and separately if the user was
removed or not.
version_added: "0.6" version_added: "0.6"
options: options:
name: name:
@ -64,7 +74,7 @@ options:
default: localhost default: localhost
priv: priv:
description: description:
- PostgreSQL privileges string in the format: table:priv1,priv2 - "PostgreSQL privileges string in the format: C(table:priv1,priv2)"
required: false required: false
default: null default: null
state: state:
@ -83,8 +93,14 @@ examples:
- code: INSERT,UPDATE/table:SELECT/anothertable:ALL - code: INSERT,UPDATE/table:SELECT/anothertable:ALL
description: Example privileges string format description: Example privileges string format
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
- 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. sudo'ing to the 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.
requirements: [ psycopg2 ] requirements: [ psycopg2 ]
author: Lorin Hochstein author: Lorin Hochstein
''' '''

Loading…
Cancel
Save