Merge pull request #1155 from jpmens/m-docs4

DOCUMENTATION for fetch,mount,ohai,easy_install; .rst template tweaks

hacking/templates/rst.j2

@@ -18,7 +18,7 @@
 @{ desc | jpfunc }@ 
 {% endfor %}
 
-{% if options is defined -%}
+{% if options -%}
 .. raw:: html
 
     <table>
@@ -33,7 +33,7 @@
     <tr>
     <td>@{ k }@</td>
     <td>@{ v.get('required',False) }@</td>
-    <td>@{ v['default'] }@</td>
+    <td>{% if v['default'] %}@{ v['default'] }@{% endif %}</td>
     <td><ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice }@</li>{% endfor -%}</ul></td>
     <td>{% for desc in v.description -%}@{ desc | html_ify }@{% endfor -%}</td>
     </tr>

library/easy_install

@@ -19,6 +19,42 @@
 # 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):
     if os.path.exists(os.path.join(env, 'bin', 'activate')):
         return 0, '', ''

library/facter

@@ -19,9 +19,23 @@
 # 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
 

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
+'''

library/mount

@@ -20,16 +20,61 @@
 # You should have received a copy of the GNU General Public License
 # 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):
 

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:

library/ohai

@@ -19,6 +19,23 @@
 # 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():
     p = subprocess.Popen(["/usr/bin/env", "ohai"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
     (out, err) = p.communicate()

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.
+   - 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"
 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.
+   - 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 ]
 author: Lorin Hochstein
 '''