Merge pull request #1655 from jpmens/docs_jumbopatch

DOCUMENTATION strings

docsite/_static/bootstrap.css

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

docsite/_themes/bootstrap/static/bootstrap.css

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

docsite/rst/moduledev.rst

@@ -347,6 +347,13 @@ Include it in your module file like this::
           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
 ++++++++++++++++++
 

hacking/module_formatter.py

@@ -100,13 +100,9 @@ def rst_ify(text):
 
     t = _ITALIC.sub(r'*' + r"\1" + r"*", text)
     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)
-    # 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
 

library/apt

@@ -24,7 +24,7 @@ DOCUMENTATION = '''
 module: apt
 short_description: Manages apt-packages
 description:
-  - Manages apt-packages (such as for Debian/Ubuntu).
+  - Manages I(apt) packages (such as for Debian/Ubuntu).
 version_added: "0.0.2"
 options:
   pkg:
@@ -40,13 +40,13 @@ options:
     choices: [ "latest", "absent", "present" ]
   update_cache:
     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
     default: "no"
     choices: [ "yes", "no" ]
   purge:
     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
     default: "no"
     choices: [ "yes", "no" ]
@@ -81,7 +81,7 @@ examples:
     - 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)
     - 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

library/apt_repository

@@ -28,7 +28,7 @@ DOCUMENTATION = '''
 module: apt_repository
 short_description: Manages apt repositores
 description:
-  - Manages apt repositores (such as for Debian/Ubuntu).
+  - Manages apt repositories (such as for Debian/Ubuntu).
 version_added: "0.7"
 options:
   repo:
@@ -43,7 +43,7 @@ options:
     default: present
     choices: [ "present", "absent" ]
 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)
    - 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

library/assemble

@@ -31,7 +31,7 @@ description:
      - Assembles a configuration file from fragments. Often a particular
        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
-       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
        produce a destination file. Files are assembled in string sorting order.
        Puppet calls this idea I(fragments).

library/command

@@ -31,7 +31,7 @@ DOCUMENTATION = '''
 module: command
 short_description: Executes a command on a remote node
 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
        processed through the shell, so variables like C($HOME) and operations
        like C("<"), C(">"), C("|"), and C("&") will not work. As such, all
@@ -70,7 +70,7 @@ examples:
    - code: "command: /sbin/shutdown -t now"
      description: "Example from Ansible Playbooks"
    - 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:
     -  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

library/cron

@@ -31,7 +31,7 @@ short_description: Manage crontab entries.
 description:
   - Use this module to manage crontab entries. This module allows you to create named
     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
     to find/check the state.'
 version_added: "0.9"
@@ -64,7 +64,7 @@ options:
   backup:
     description:
       - 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
     default: false
     aliases: []

library/debug

@@ -28,12 +28,12 @@ description:
        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
-       mode (using the -v option).
+       mode (using the C(-v) option).
 version_added: "0.8"
 options:
   msg:
     description:
-      - The customized message that is printed. If ommited, prints a generic
+      - The customized message that is printed. If omitted, prints a generic
         message.
     required: false
     default: "Hello world!"

library/ec2

@@ -19,12 +19,12 @@ DOCUMENTATION = '''
 module: ec2
 short_description: create an instance in ec2, return instanceid
 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"
 options:
   keypair:
     description:
-      - keypair to use on the instance
+      - key pair to use on the instance
     required: true
     default: null
     aliases: []
@@ -42,19 +42,19 @@ options:
     aliases: []
   image:
     description:
-       - emi (or ami) to use for the instance
+       - I(emi) (or I(ami)) to use for the instance
     required: true
     default: null
     aliases: []
   kernel:
     description:
-      - kernel eki to use for the instance
+      - kernel I(eki) to use for the instance
     required: false
     default: null
     aliases: []
   ramdisk:
     description:
-      - ramdisk eri to use for the instance
+      - ramdisk I(eri) to use for the instance
     required: false
     default: null
     aliases: []
@@ -66,7 +66,7 @@ options:
     aliases: []
   ec2_url:
     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
     default: null
     aliases: []

library/fail

@@ -24,12 +24,12 @@ module: fail
 short_description: Fail with custom message
 description:
      - 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"
 options:
   msg:
     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.
     required: false
     default: "'Failed as requested from task'"

library/fetch

@@ -12,7 +12,7 @@ version_added: "0.2"
 options:
   src:
     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.
     required: true
     default: null
@@ -20,7 +20,7 @@ options:
   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
+        directory is C(/backup) a I(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

library/file

@@ -35,11 +35,11 @@ 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).
+       the file module - including M(copy), M(template), and M(assemble).
 options:
   path:
     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
     default: []
     aliases: []
@@ -59,7 +59,7 @@ options:
     default: null
     choices: []
     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:
     required: false
     default: null
@@ -85,7 +85,7 @@ options:
     description:
       - 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
-        the policy if available
+        policy if available
   serole:
     required: false
     default: null

library/fireball

@@ -24,7 +24,7 @@ module: fireball
 short_description: Enable fireball mode on remote node
 description:
      - 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.
      - Starting a new fireball as a given user terminates any existing user fireballs.
      - Fireball mode is AES encrypted
@@ -50,7 +50,7 @@ examples:
                  connection: ssh
                  sudo: yes
                  tasks:
-                     - action: fireball 
+                     - action: fireball
            - hosts: devservers
                  connection: fireball
                  tasks:
@@ -160,7 +160,7 @@ def command(data):
     log("got stdout: %s" % stdout)
 
     return dict(stdout=stdout, stderr=stderr)
-  
+
 def fetch(data):
     if 'in_path' not in data:
         return dict(failed=True, msg='internal error: in_path is required')
@@ -179,7 +179,7 @@ def put(data):
         return dict(failed=True, msg='internal error: data is required')
     if 'out_path' not in data:
         return dict(failed=True, msg='internal error: out_path is required')
-    
+
     # FIXME: should probably support chunked file transfer for binary files
     # at some point.  For now, just base64 encodes the file
     # so don't use it to move ISOs, use rsync.
@@ -204,7 +204,7 @@ def serve(module, password, port, minutes):
     # password as a variable in ansible is never logged though, so it serves well
 
     key = AesKey.Read(password)
- 
+
     while True:
 
         data = socket.recv()
@@ -264,10 +264,10 @@ def main():
     if not HAS_ZMQ:
         module.fail_json(msg="zmq is not installed")
     if not HAS_KEYCZAR:
-        module.fail_json(msg="keyczar is not installed")    
+        module.fail_json(msg="keyczar is not installed")
 
     daemonize(module, password, port, minutes)
-   
+
 
 # this is magic, see lib/ansible/module_common.py
 #<<INCLUDE_ANSIBLE_MODULE_COMMON>>

library/get_url

@@ -30,7 +30,7 @@ module: get_url
 short_description: Downloads files from HTTP, HTTPS, or FTP to node
 description:
      - 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"
 options:
   url:
@@ -42,13 +42,13 @@ options:
   dest:
     description:
       - 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
     default: null
   thirsty:
     description:
       - 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
         local files. prior to 0.6, acts if C(yes) by default.
     version_added: "0.7"

library/git

@@ -25,13 +25,13 @@ author: Michael DeHaan
 version_added: 0.0.1
 short_description: Deploy software (or files) from git checkouts
 description:
-    - Manage git checkouts of repositories to deploy files or software.
+    - Manage I(git) checkouts of repositories to deploy files or software.
 options:
     repo:
         required: true
         aliases: [ name ]
         description:
-            - git, ssh, or http protocol address of the git repository.
+            - git, SSH, or HTTP protocol address of the git repository.
     dest:
         required: true
         description:
@@ -41,7 +41,7 @@ options:
         default: "HEAD"
         description:
             - 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:
         required: false
         default: "origin"
@@ -51,8 +51,9 @@ options:
         required: false
         default: "yes"
         choices: [ yes, no ]
+        version_added: "0.7"
         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
               'yes' and could not be disabled.
 examples:

library/lineinfile

@@ -54,7 +54,7 @@ options:
     required: false
     description:
       - 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:
     required: false
     default: EOF

library/mysql_db

@@ -65,18 +65,18 @@ options:
     default: null
   target:
     description:
-      - Where to dump/get the .sql file
+      - Where to dump/get the C(.sql) file
     required: true
 examples:
    - code: "mysql_db: db=bobdata state=present"
      description: Create a new database with name 'bobdata'
 notes:
    - 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
      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 ]
 author: Mark Theunissen
 '''

library/nagios

@@ -21,10 +21,10 @@ module: nagios
 short_description: Perform common tasks in Nagios related to downtime and notifications. 
 description:
   - "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).
   - 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
 options:
   action:
@@ -47,13 +47,13 @@ options:
   author:
     description:
      - Author to leave downtime comments as.
-      - Only useable with the C(downtime) action.
+      - Only usable with the C(downtime) action.
     required: false
     default: Ansible
   minutes:
     description:
       - Minutes to schedule downtime for.
-      - Only useable with the C(downtime) action.
+      - Only usable with the C(downtime) action.
     required: false
     default: 30
   services:

library/ohai

@@ -22,9 +22,9 @@
 DOCUMENTATION = '''
 ---
 module: ohai
-short_description: Returns inventory data from I(ohai)
+short_description: Returns inventory data from I(Ohai)
 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 
        returns JSON inventory data.
        I(Ohai) data is a bit more verbose and nested than I(facter).

library/ping

@@ -22,10 +22,10 @@
 DOCUMENTATION = '''
 ---
 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:
-   - 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)
 options: {}
 examples:

library/pip

@@ -34,7 +34,7 @@ options:
     default: null
   version:
     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
     default: null
   requirements:
@@ -44,7 +44,7 @@ options:
     default: null
   virtualenv:
     description:
-      - An optional path to a virtualenv directory to install into
+      - An optional path to a I(virtualenv) directory to install into
     required: false
     default: null
   state:
@@ -63,7 +63,7 @@ examples:
    - code: "pip: requirements=/srv/webapps/my_app/src/requirements.txt"
      description: Install specified python requirements.
    - 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:
    - 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" ]

library/postgresql_db

@@ -57,10 +57,11 @@ options:
     choices: [ "present", "absent" ]
 examples:
    - code: "postgresql_db: db=acme"
-     description: Create a new database with name 'acme'
+     description: Create a new database with name C(acme)
 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 ]
 author: Lorin Hochstein
 '''

library/postgresql_user

@@ -28,7 +28,7 @@ description:
      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
+   - 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
      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
@@ -53,7 +53,7 @@ options:
     default: null
   fail_on_user:
     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
     default: yes
     choices: [ "yes", "no" ]

library/raw

@@ -8,7 +8,7 @@ options: {}
 description: 
      - 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 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
        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
@@ -18,6 +18,6 @@ description:
        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
+      description: Example from C(/usr/bin/ansible) to bootstrap a legacy python 2.4 host
 author: Michael DeHaan
 '''

library/script

@@ -17,7 +17,7 @@ examples:
   - description: "Example from Ansible Playbooks"
     code: "script: /some/local/script.sh --some-arguments 1234"
 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
 """
 

library/seboolean

@@ -32,7 +32,7 @@ options:
     default: null
   persistent:
     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
     default: no
     choices: [ "yes", "no" ]

library/selinux

@@ -28,7 +28,7 @@ version_added: "0.7"
 options:
   policy:
     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
     default: null
   state:

library/service

@@ -35,10 +35,9 @@ options:
         required: false
         choices: [ started, stopped, restarted, reloaded ]
         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:
         required: false
         version_added: "0.7"

library/setup

@@ -44,10 +44,10 @@ notes:
       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 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:
     - 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
 '''
 

library/shell

@@ -24,9 +24,10 @@ options:
     default: null
   chdir:
     description:
-      - cd into this directory before running the command (0.6 and later)
+      - cd into this directory before running the command
     required: false
     default: null
+    version_added: "0.6"
   executable:
     description:
       - 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"
      description: Execute the command in remote shell
 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
       playbooks will follow the trend of using M(command) unless M(shell) is
       explicitly required. When running ad-hoc commands, use your best

library/slurp

@@ -28,7 +28,7 @@ description:
 options:
   src:
     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.
     required: true
     default: null

library/subversion

@@ -38,7 +38,7 @@ options:
     default: null
   force:
     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
     default: yes
     choices: [ "yes", "no" ]
@@ -46,7 +46,7 @@ examples:
    - code: "subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout"
      description: Export subversion repository in a specified folder
 notes:
-   - Requires subversion and grep on the client.
+   - Requires I(subversion) and I(grep) on the client.
 requirements: [ ]
 author: Dane Summers
 '''

library/supervisorctl

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

library/svr4pkg

@@ -40,7 +40,7 @@ options:
   state:
     description:
       - 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.
     required: true
     choices: ["present", "absent"]
@@ -49,7 +49,7 @@ options:
     description:
       - 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)."
-      - 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:
     description:
       - HTTP[s] proxy to be used if C(src) is a URL.

library/user

@@ -52,7 +52,7 @@ options:
     append:
         required: false
         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).
     shell:
         required: false
@@ -73,36 +73,36 @@ options:
         default: "present"
         choices: [ present, absent ]
         description:
-            - Whether the account should exist.  When I(absent), removes
+            - Whether the account should exist.  When C(absent), removes
               the user account.
     createhome:
         required: false
         default: "yes"
         choices: [ yes, no ]
         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.
     system:
         required: false
         default: "no"
         choices: [ yes, no ]
         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.
     force:
         required: false
         default: "no"
         choices: [ yes, no ]
         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:
         required: false
         default: "no"
         choices: [ yes, no ]
         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:
         required: false
         default: "no"

library/yum

@@ -61,7 +61,7 @@ options:
     
   disablerepo:
     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
         Multiple repos separated with a ','
         New in version 0.9.