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"\1", t)
+    t = _MODULE.sub(r'``' + r"\1" + r"``", t)
     t = _URL.sub(r"\1", t)
-    # ditto
-    # t = _CONST.sub(r'``' + r"\1" + r"``", t)
-    t = _CONST.sub(r"\1", t)
+    t = _CONST.sub(r'``' + r"\1" + r"``", 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,15 +12,15 @@ 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
     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
+        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"