From 754888d89619ba05e5432570a13c111735e8be90 Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Sun, 30 Sep 2012 12:21:35 +0200 Subject: [PATCH] DOCUMENTATION for fetch,mount,ohai,easy_install - .rst now supresses default if none is set (looks better in HTML) - .rst now handles empty options list - Fixed postgresql_user and mysql_user because YAML contained colons - docs for facter --- hacking/templates/rst.j2 | 4 +-- library/easy_install | 36 ++++++++++++++++++++++ library/facter | 20 +++++++++++-- library/fetch | 34 +++++++++++++++++++++ library/mount | 65 +++++++++++++++++++++++++++++++++------- library/mysql_user | 4 +-- library/ohai | 17 +++++++++++ library/postgresql_user | 28 +++++++++++++---- 8 files changed, 185 insertions(+), 23 deletions(-) diff --git a/hacking/templates/rst.j2 b/hacking/templates/rst.j2 index 6a2108a638f..f56c57b86dd 100644 --- a/hacking/templates/rst.j2 +++ b/hacking/templates/rst.j2 @@ -18,7 +18,7 @@ @{ desc | jpfunc }@ {% endfor %} -{% if options is defined -%} +{% if options -%} .. raw:: html @@ -33,7 +33,7 @@ - + diff --git a/library/easy_install b/library/easy_install index cacd5203ede..bd2161c3267 100755 --- a/library/easy_install +++ b/library/easy_install @@ -19,6 +19,42 @@ # along with Ansible. If not, see . # +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): if os.path.exists(os.path.join(env, 'bin', 'activate')): return 0, '', '' diff --git a/library/facter b/library/facter index ade4544bc0a..f274a35df45 100755 --- a/library/facter +++ b/library/facter @@ -19,9 +19,23 @@ # along with Ansible. If not, see . # -# things that must be installed to use this -# facter -# ruby-json + +DOCUMENTATION = ''' +--- +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 diff --git a/library/fetch b/library/fetch index 9132aeebbed..71c19bc8365 100755 --- a/library/fetch +++ b/library/fetch @@ -1 +1,35 @@ # 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 +''' diff --git a/library/mount b/library/mount index ea929f0acff..12c75f47956 100755 --- a/library/mount +++ b/library/mount @@ -20,16 +20,61 @@ # You should have received a copy of the GNU General Public License # along with Ansible. If not, see . -# mount module - mount fs and define in fstab -# usage: -# -# mount name=mountpoint, src=device_to_be_mounted fstype=fstype -# opts=mount_opts, dump=0 passno=0 state=[present|absent|mounted|unmounted] -# -# absent == remove from fstab and unmounted -# present == add to fstab, do not change mount state -# mounted == add to fstab if not there and make sure it is mounted -# unmounted == do not change fstab state, but unmount +DOCUMENTATION = ''' +--- +module: mount +short_description: Control active and configured mount points +description: + - This module controls active and configured mount points in C(/etc/fstab). +version_added: "0.6" +options: + name: + 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): diff --git a/library/mysql_user b/library/mysql_user index e35cce3c02d..be9cd00b3ac 100755 --- a/library/mysql_user +++ b/library/mysql_user @@ -48,7 +48,7 @@ options: default: null login_password: description: - - The passwordused to authenticate with + - The password used to authenticate with required: false default: null login_host: @@ -58,7 +58,7 @@ options: default: localhost priv: description: - - MySQL privileges string in the format: db.table:priv1,priv2 + - "MySQL privileges string in the format: C(db.table:priv1,priv2)" required: false default: null state: diff --git a/library/ohai b/library/ohai index 826ac50538a..5a8281a80c2 100755 --- a/library/ohai +++ b/library/ohai @@ -19,6 +19,23 @@ # along with Ansible. If not, see . # +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(): p = subprocess.Popen(["/usr/bin/env", "ohai"], stdout=subprocess.PIPE, stderr=subprocess.PIPE) (out, err) = p.communicate() diff --git a/library/postgresql_user b/library/postgresql_user index 99de1414b2d..5c9c2025d27 100755 --- a/library/postgresql_user +++ b/library/postgresql_user @@ -21,9 +21,19 @@ DOCUMENTATION = ''' module: postgresql_user short_description: Adds or removes a users (roles) from a PostgreSQL database. description: - - Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users access to an existing database or tables. - - 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. + - Add or remove PostgreSQL users (roles) from a remote host and, optionally, + grant the users access to an existing database or tables. + - 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" options: name: @@ -64,7 +74,7 @@ options: default: localhost priv: description: - - PostgreSQL privileges string in the format: table:priv1,priv2 + - "PostgreSQL privileges string in the format: C(table:priv1,priv2)" required: false default: null state: @@ -83,8 +93,14 @@ examples: - code: INSERT,UPDATE/table:SELECT/anothertable:ALL description: Example privileges string format notes: - - The default authentication assumes that you are either logging in as or 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. + - The default authentication assumes that you are either logging in as or + 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 ] author: Lorin Hochstein '''
@{ k }@ @{ v.get('required',False) }@@{ v['default'] }@{% if v['default'] %}@{ v['default'] }@{% endif %}
    {% for choice in v.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
 {% for desc in v.description -%}@{ desc | html_ify }@{% endfor -%}