Tweak DOCUMENTATION YAML as per latest 991

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):

get_url

@@ -28,39 +28,43 @@ DOCUMENTATION = '''
 ---
 module: get_url
 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.
 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
+      description:
-            directory, the basename of the file on the remote server will be used. If
+        - absolute path of where to download the file to.
-            a directory, 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, I(thirsty=yes) must also be set.
       required: true
       default: null
   - thirsty:
-      description: if yes, will download the file every time and replace the
+      description:
-           file if the contents change. if no, the file will only be downloaded if
+        - if C(yes), will download the file every time and replace the
-           the destination does not exist. Generally should be 'yes' only for small
+          file if the contents change. if C(no), the file will only be downloaded if
-           local files. prior to 0.6, acts if 'yes' by default.
+           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: >
+notes:
-    This module doesn't support proxies or passwords.
+    - This module doesn't support proxies or passwords.
+    - Also see the M(template) module.
 # informational: requirements for nodes
 requirements: [ urllib2, urlparse ]
 '''

raw

@@ -3,18 +3,18 @@
 DOCUMENTATION = '''
 ---
 module: raw
-short_description: Executes a low-down and dirty SSH command, not going through the module subsystem.
+short_description: Executes a low-down and dirty SSH command
-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 first
+       subsystem. This is useful and should only be done in two cases. The
-     case is installing python-simplejson on older (python 2.4 and before)
+       first case is installing python-simplejson on older (Python 2.4 and
-     hosts that need it as a dependency to run modules, since nearly all core
+       before) hosts that need it as a dependency to run modules, since nearly
-     modules require it. Another is speaking to any devices such as routers
+       all core modules require it. Another is speaking to any devices such as
-     that do not have any Python installed. In any other case, using the
+       routers that do not have any Python installed. In any other case, using
-     'shell' or 'command' module is much more appropriate. Arguments given to
+       the M(shell) or M(command) module is much more appropriate. Arguments
-     'raw' are run directly through the configured remote shell and only output
+       given to M(raw) are run directly through the configured remote shell and
-     is returned. There is no error detection or change handler support for
+       only output is returned. There is no error detection or change handler
-     this module
+       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

setup

@@ -30,19 +30,19 @@ DOCUMENTATION = '''
 ---
 module: setup
 short_description: Gathers facts about remote hosts
-description: >
+description: 
-     This module is automatically called by playbooks to gather useful
+     - 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
+       executed directly by C(/usr/bin/ansible) to check what variables are
-     available to a host. Ansible provides many 'facts' about the system,
+       available to a host. Ansible provides many I(facts) about the system,
        automatically.
-notes: >
+notes: 
-    More ansible facts will be added with successive releases. If facter or
+    - More ansible facts will be added with successive releases. If I(facter) or
-    ohai are installed, variables from these programs will also be snapshotted
+      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