DOCS: standardize on EXAMPLES (a.k.a. Docs-JumboPatch JetLag Edition)

Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

library/packaging/apt

@@ -87,27 +87,38 @@ author: Matthew Williams
 notes:
    - Three of the upgrade modes (C(full), C(safe) and its alias C(yes)) require C(aptitude), otherwise
      C(apt-get) suffices.
-examples:
-    - code: "apt: pkg=foo update_cache=yes"
-      description: Update repositories cache and install C(foo) package
-    - code: "apt: pkg=foo state=absent"
-      description: Remove C(foo) package
-    - code: "apt: pkg=foo state=present"
-      description: Install the package C(foo)
-    - code: "apt: pkg=foo=1.00 state=present"
-      description: Install the version '1.00' of package C(foo)
-    - code: "apt: pkg=nginx state=latest default_release=squeeze-backports update_cache=yes"
-      description: Update the repository cache and update package C(nginx) 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-reccomends)
-    - code: "apt: upgrade=dist"
-      description: Update all packages to the latest version
-    - code: "apt: update_cache=yes"
-      description: Run the equivalent of C(apt-get update) as a separate step
-    - code: "apt: update_cache=yes cache_valid_time=3600"
-      description: Only run C(update_cache=yes) if the last one is more than more than 3600 seconds ago
 '''
 
+EXAMPLES = '''
+# Update repositories cache and install "foo" package
+- apt: pkg=foo update_cache=yes
+
+# Remove "foo" package
+- apt: pkg=foo state=absent
+
+# Install the package "foo"
+- apt: pkg=foo state=present
+
+# Install the version '1.00' of package "foo"
+- apt: pkg=foo=1.00 state=present
+
+# Update the repository cache and update package "nginx" to latest version using default release squeeze-backport
+- apt: pkg=nginx state=latest default_release=squeeze-backports update_cache=yes
+
+# Install latest version of "openjdk-6-jdk" ignoring "install-reccomends"
+- apt: pkg=openjdk-6-jdk state=latest install_recommends=no
+
+# Update all packages to the latest version
+- apt: upgrade=dist
+
+# Run the equivalent of "apt-get update" as a separate step
+- apt: update_cache=yes
+
+# Only run "update_cache=yes" if the last one is more than more than 3600 seconds ago
+- apt: update_cache=yes cache_valid_time=3600
+'''
+
+
 import traceback
 # added to stave off future warnings about apt api
 import warnings

library/packaging/apt_key

@@ -48,17 +48,23 @@ options:
         default: present
         description:
             - used to specify if key is being added or revoked
-examples:
-    - code: "apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present"
-      description: Add an Apt signing key, uses whichever key is at the URL
-    - code: "apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present"
-      description: Add an Apt signing key, will not download if present
-    - code: "apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent"
-      description: Remove an Apt signing key, uses whichever key is at the URL
-    - code: "apt_key: id=473041FA state=absent"
-      description: Remove a Apt specific signing key
 '''
 
+EXAMPLES = '''
+# Add an Apt signing key, uses whichever key is at the URL
+- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present
+
+# Add an Apt signing key, will not download if present
+- apt_key: id=473041FA url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=present
+
+# Remove an Apt signing key, uses whichever key is at the URL
+- apt_key: url=https://ftp-master.debian.org/keys/archive-key-6.0.asc state=absent
+
+# Remove a Apt specific signing key
+- apt_key: id=473041FA state=absent
+'''
+
+
 # FIXME: standardize into module_common
 from urllib2 import urlopen, URLError
 from traceback import format_exc

library/packaging/apt_repository

@@ -47,14 +47,17 @@ notes:
    - 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
-examples:
-- code: "apt_repository: repo=ppa:nginx/stable"
-  description: Add nginx stable repository from PPA
-- code: "apt_repository: repo='deb http://archive.canonical.com/ubuntu hardy partner'"
-  description: Add specified repository into sources.
 requirements: [ python-apt ]
 '''
 
+EXAMPLES = '''
+# Add nginx stable repository from PPA
+- apt_repository: repo=ppa:nginx/stable
+
+# Add specified repository into sources.
+- apt_repository: repo='deb http://archive.canonical.com/ubuntu hardy partner'
+'''
+
 import platform
 
 try:

library/packaging/easy_install

@@ -57,11 +57,6 @@ options:
         C(pyvenv), C(virtualenv), C(virtualenv2).
     required: false
     default: virtualenv
-examples:
-   - code: "easy_install: name=pip"
-     description: "Examples from Ansible Playbooks"
-   - code: "easy_install: name=flask virtualenv=/webapps/myapp/venv"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)"
 notes:
     - Please note that the M(easy_install) module can only install Python
       libraries. Thus this module is not able to remove libraries. It is
@@ -73,6 +68,14 @@ requirements: [ "virtualenv" ]
 author: Matt Wright
 '''
 
+EXAMPLES = '''
+# Examples from Ansible Playbooks
+- easy_install: name=pip
+
+# Install Flast into the specified virtualenv.
+- easy_install: name=flask virtualenv=/webapps/myapp/venv
+'''
+
 def _is_package_installed(module, name, easy_install):
     cmd = '%s --dry-run %s' % (easy_install, name)
     rc, status_stdout, status_stderr = module.run_command(cmd)

library/packaging/macports

@@ -46,11 +46,11 @@ options:
 notes:  []
 '''
 EXAMPLES = '''
-macports: name=foo state=present
-macports: name=foo state=present update_cache=yes
-macports: name=foo state=absent
-macports: name=foo state=active
-macports: name=foo state=inactive
+- macports: name=foo state=present
+- macports: name=foo state=present update_cache=yes
+- macports: name=foo state=absent
+- macports: name=foo state=active
+- macports: name=foo state=inactive
 '''
 
 

library/packaging/npm

@@ -65,21 +65,29 @@ options:
     required: false
     default: present
     choices: [ "present", "absent", "latest" ]
-examples:
-   - code: "npm: name=coffee-script path=/app/location"
-     description: Install I(coffee-script) node.js package.
-   - code: "npm: name=coffee-script version=1.6.1 path=/app/location"
-     description: Install I(coffee-script) node.js package on version 1.6.1.
-   - code: "npm: name=coffee-script global=yes"
-     description: Install I(coffee-script) node.js package globally.
-   - code: "npm: name=coffee-script global=yes state=absent"
-     description: Remove the globally package I(coffee-script).
-   - code: "npm: path=/app/location"
-     description: Install packages based on package.json.
-   - code: "npm: path=/app/location state=latest"
-     description: Update packages based on package.json to their latest version.
-   - code: "npm: path=/app/location executable=/opt/nvm/v0.10.1/bin/npm state=present"
-     description: Install packages based on package.json using the npm installed with nvm v0.10.1.
+'''
+
+EXAMPLES = '''
+description: Install "coffee-script" node.js package.
+- npm: name=coffee-script path=/app/location
+
+description: Install "coffee-script" node.js package on version 1.6.1.
+- npm: name=coffee-script version=1.6.1 path=/app/location
+
+description: Install "coffee-script" node.js package globally.
+- npm: name=coffee-script global=yes
+
+description: Remove the globally package "coffee-script".
+- npm: name=coffee-script global=yes state=absent
+
+description: Install packages based on package.json.
+- npm: path=/app/location
+
+description: Update packages based on package.json to their latest version.
+- npm: path=/app/location state=latest
+
+description: Install packages based on package.json using the npm installed with nvm v0.10.1.
+- npm: path=/app/location executable=/opt/nvm/v0.10.1/bin/npm state=present
 '''
 
 import os

library/packaging/openbsd_pkg

@@ -40,13 +40,17 @@ options:
           - C(present) will make sure the package is installed.
             C(latest) will make sure the latest version of the package is installed.
             C(absent) will make sure the specified package is not installed.
-examples:
-    - description: Make sure nmap is installed
-      code: "openbsd_pkg: name=nmap state=present"
-    - description: Make sure nmap is the latest version
-      code: "openbsd_pkg: name=nmap state=latest"
-    - description: Make sure nmap is not installed
-      code: "openbsd_pkg: name=nmap state=absent"
+'''
+
+EXAMPLES = '''
+# Make sure nmap is installed
+- openbsd_pkg: name=nmap state=present
+
+# Make sure nmap is the latest version
+- openbsd_pkg: name=nmap state=latest
+
+# Make sure nmap is not installed
+- openbsd_pkg: name=nmap state=absent
 '''
 
 # select whether we dump additional debug info through syslog

library/packaging/opkg

@@ -45,10 +45,10 @@ options:
 notes:  []
 '''
 EXAMPLES = '''
-opkg: name=foo state=present
-opkg: name=foo state=present update_cache=yes
-opkg: name=foo state=absent
-opkg: name=foo,bar state=absent
+- opkg: name=foo state=present
+- opkg: name=foo state=present update_cache=yes
+- opkg: name=foo state=absent
+- opkg: name=foo,bar state=absent
 '''
 
 

library/packaging/pacman

@@ -47,16 +47,20 @@ options:
 
 author: Afterburn
 notes:  []
-examples:
-    - code: "pacman: name=foo state=installed"
-      description: install package foo
-    - code: "pacman: name=foo state=absent"
-      description: remove package foo
-    - code: "pacman: name=foo,bar state=absent"
-      description: remove packages foo and bar 
-    - code: "pacman: name=bar, state=installed, update_cache=yes"
-      description: update the package database (pacman -Syy) and install bar (bar will be the updated if a newer version exists) 
-      
+'''
+
+EXAMPLES = '''
+# Install package foo
+- pacman: name=foo state=installed
+
+# Remove package foo
+- pacman: name=foo state=absent
+
+# Remove packages foo and bar 
+- pacman: name=foo,bar state=absent
+
+# Update the package database (pacman -Syy) and install bar (bar will be the updated if a newer version exists) 
+- pacman: name=bar, state=installed, update_cache=yes
 '''
 
 

library/packaging/pip

@@ -91,31 +91,41 @@ options:
     required: false
     default: null
     version_added: "1.0"
-examples:
-   - code: "pip: name=flask"
-     description: Install I(flask) python package.
-   - code: "pip: name=flask version=0.8"
-     description: Install I(flask) python package on version 0.8.
-   - code: "pip: name='svn+http://myrepo/svn/MyApp#egg=MyApp'"
-     description: Install I(MyApp) using one of the remote protocols (bzr+,hg+,git+,svn+) or tarballs (zip, gz, bz2) C(pip) supports. You do not have to supply '-e' option in extra_args. For these source names, C(use_mirrors) is ignored and not applicable.
-   - code: "pip: name=flask virtualenv=/my_app/venv"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), inheriting none of the globally installed modules"
-   - code: "pip: name=flask virtualenv=/my_app/venv virtualenv_site_packages=yes"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), inheriting globally installed modules"
-   - code: "pip: name=flask virtualenv=/my_app/venv virtualenv_command=virtualenv-2.7"
-     description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv), using Python 2.7"
-   - code: "pip: requirements=/my_app/requirements.txt"
-     description: Install specified python requirements.
-   - code: "pip: requirements=/my_app/requirements.txt virtualenv=/my_app/venv"
-     description: Install specified python requirements in indicated I(virtualenv).
-   - code: "pip: requirements=/my_app/requirements.txt extra_args='-i https://example.com/pypi/simple'"
-     description: Install specified python requirements and custom Index URL.
 notes:
    - Please note that virtualenv (U(http://www.virtualenv.org/)) must be installed on the remote host if the virtualenv parameter is specified.
 requirements: [ "virtualenv", "pip" ]
 author: Matt Wright
 '''
 
+EXAMPLES = '''
+# Install (flask) python package.
+- pip: name=flask
+
+# Install (flask) python package on version 0.8.
+- pip: name=flask version=0.8
+
+# Install (MyApp) using one of the remote protocols (bzr+,hg+,git+,svn+) or tarballs (zip, gz, bz2) (pip) supports. You do not have to supply '-e' option in extra_args. For these source names, (use_mirrors) is ignored and not applicable.
+- pip: name='svn+http://myrepo/svn/MyApp#egg=MyApp'
+
+# Install (Flask) into the specified (virtualenv), inheriting none of the globally installed modules
+- pip: name=flask virtualenv=/my_app/venv
+
+# Install (Flask) into the specified (virtualenv), inheriting globally installed modules
+- pip: name=flask virtualenv=/my_app/venv virtualenv_site_packages=yes
+
+# Install (Flask) into the specified (virtualenv), using Python 2.7
+- pip: name=flask virtualenv=/my_app/venv virtualenv_command=virtualenv-2.7
+
+# Install specified python requirements.
+- pip: requirements=/my_app/requirements.txt
+
+# Install specified python requirements in indicated (virtualenv).
+- pip: requirements=/my_app/requirements.txt virtualenv=/my_app/venv
+
+# Install specified python requirements and custom Index URL.
+- pip: requirements=/my_app/requirements.txt extra_args='-i https://example.com/pypi/simple'
+'''
+
 
 def _get_full_name(name, version=None):
     if version is None:

library/packaging/pkgin

@@ -40,13 +40,17 @@ options:
         default: present
 author: Shaun Zinck
 notes:  []
-examples:
-    - code: "pkgin: name=foo state=present"
-      description: install package foo"
-    - code: "pkgin: name=foo state=absent"
-      description: remove package foo
-    - code: "pkgin: name=foo,bar state=absent"
-      description: remove packages foo and bar 
+'''
+
+EXAMPLES = '''
+# install package foo"
+- pkgin: name=foo state=present
+
+# remove package foo
+- pkgin: name=foo state=absent
+
+# remove packages foo and bar 
+- pkgin: name=foo,bar state=absent
 '''
 
 

library/packaging/pkgng

@@ -54,13 +54,14 @@ options:
 author: bleader
 notes:
     - When using pkgsite, be careful that already in cache packages won't be downloaded again.
-examples:
-    - code: "pkgng: name=foo state=present"
-      description: install package foo"
-    - code: "pkgng: name=foo state=absent"
-      description: remove package foo
-    - code: "pkgng: name=foo,bar state=absent"
-      description: remove packages foo and bar 
+'''
+
+EXAMPLES = '''
+# Install package foo
+- pkgng: name=foo state=present
+
+# Remove packages foo and bar 
+- pkgng: name=foo,bar state=absent
 '''
 
 

library/packaging/redhat_subscription

@@ -59,11 +59,17 @@ options:
             - Specify a subscription pool name to consume.  Regular expressions accepted.
         required: False
         default: '^$'
-examples:
-    - code: redhat_subscription action=register username=joe_user password=somepass autosubscribe=true
-      description: Register as user I(joe_user) with password I(somepass) and auto-subscribe to available content.
-    - code: redhat_subscription action=register activationkey=1-222333444 pool='^(Red Hat Enterprise Server|Red Hat Virtualization)$'
-      description: Register with activationkey I(1-222333444) and consume subscriptions matching the names I(Red hat Enterprise Server) and I(Red Hat Virtualization)
+'''
+
+EXAMPLES = '''
+# Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
+- redhat_subscription: action=register username=joe_user password=somepass autosubscribe=true
+
+# Register with activationkey (1-222333444) and consume subscriptions matching
+# the names (Red hat Enterprise Server) and (Red Hat Virtualization)
+- redhat_subscription: action=register
+                       activationkey=1-222333444
+                       pool='^(Red Hat Enterprise Server|Red Hat Virtualization)$'
 '''
 
 import os

library/packaging/rhn_channel

@@ -43,7 +43,7 @@ options:
 '''
 
 EXAMPLES = '''
-rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme
+- rhn_channel: name=rhel-x86_64-server-v2vwin-6 sysname=server01 url=https://rhn.redhat.com/rpc/api user=rhnuser password=guessme
 '''
 
 import xmlrpclib

library/packaging/rhn_register

@@ -44,22 +44,31 @@ options:
             - Optionally specify a list of comma-separated channels to subscribe to upon successful registration.
         required: false
         default: []
+'''
 
-examples:
-    - code: rhn_register state=absent username=joe_user password=somepass
-      description: Unregister system from RHN.
+EXAMPLES = '''
+# Unregister system from RHN.
+- code: rhn_register state=absent username=joe_user password=somepass
 
-    - code: rhn_register state=present username=joe_user password=somepass
-      description: Register as user I(joe_user) with password I(somepass) and auto-subscribe to available content.
+# Register as user (joe_user) with password (somepass) and auto-subscribe to available content.
+- code: rhn_register state=present username=joe_user password=somepass
 
-    - code: rhn_register state=present activationkey=1-222333444 enable_eus=true
-      description: Register with activationkey I(1-222333444) and enable extended update support.
+# Register with activationkey (1-222333444) and enable extended update support.
+- code: rhn_register state=present activationkey=1-222333444 enable_eus=true
 
-    - code: rhn_register state=present username=joe_user password=somepass server_url=https://xmlrpc.my.satellite/XMLRPC
-      description: Register as user I(joe_user) with password I(somepass) against a satellite server specified by I(server_url).
+# Register as user (joe_user) with password (somepass) against a satellite
+# server specified by (server_url).
+- rhn_register:
+    state=present
+    username=joe_user
+    password=somepass
+    server_url=https://xmlrpc.my.satellite/XMLRPC
 
-    - code: rhn_register state=present username=joe_user password=somepass channels=rhel-x86_64-server-6-foo-1,rhel-x86_64-server-6-bar-1
-      description: Register as user I(joe_user) with password I(somepass) and enable channels I(rhel-x86_64-server-6-foo-1) and I(rhel-x86_64-server-6-bar-1).
+# Register as user (joe_user) with password (somepass) and enable
+# channels (rhel-x86_64-server-6-foo-1) and (rhel-x86_64-server-6-bar-1).
+- rhn_register: state=present username=joe_user
+                password=somepass
+                channels=rhel-x86_64-server-6-foo-1,rhel-x86_64-server-6-bar-1
 '''
 
 import sys

library/packaging/svr4pkg

@@ -53,15 +53,20 @@ options:
   proxy:
     description:
       - HTTP[s] proxy to be used if C(src) is a URL.
-
-examples:
-  - code: svr4pkg name=CSWcommon src=/tmp/cswpkgs.pkg state=present
-    description: Install a package from an already copied file
-  - code: 'svr4pkg name=CSWpkgutil src=http://get.opencsw.org/now state=present'
-    description: Install a package directly from an http site
-  - code: svr4pkg name=SUNWgnome-sound-recorder state=absent
-    description: Ensure that a package is not installed.
 '''
+
+EXAMPLES = '''
+# Install a package from an already copied file
+- svr4pkg: name=CSWcommon src=/tmp/cswpkgs.pkg state=present
+
+# Install a package directly from an http site
+- svr4pkg: name=CSWpkgutil src=http://get.opencsw.org/now state=present
+
+# Ensure that a package is not installed.
+- svr4pkg: name=SUNWgnome-sound-recorder state=absent
+'''
+
+
 import os
 import tempfile
 

library/packaging/yum

@@ -86,17 +86,18 @@ options:
     default: "no"
     choices: ["yes", "no"]
     aliases: []
-
-examples:
-   - code: yum name=httpd state=latest
-   - code: yum name=httpd state=removed
-   - code: yum name=httpd enablerepo=testing state=installed
 notes: []
 # informational: requirements for nodes
 requirements: [ yum, rpm ]
 author: Seth Vidal
 '''
 
+EXAMPLES = '''
+- yum: name=httpd state=latest
+- yum: name=httpd state=removed
+- yum: name=httpd enablerepo=testing state=installed
+'''
+
 def_qf = "%{name}-%{version}-%{release}.%{arch}"
 
 repoquery='/usr/bin/repoquery'

library/packaging/zypper

@@ -60,16 +60,20 @@ options:
         choices: [ "yes", "no" ]
         aliases: []
 
-examples:
-    - code: "zypper: name=nmap state=present"
-    - code: "zypper: name=nmap state=latest"
-    - code: "zypper: name=nmap state=absent"
 notes: []
 # informational: requirements for nodes
 requirements: [ zypper, rpm ]
 author: Patrick Callahan
 '''
 
+EXAMPLES = '''
+# Install "nmap"
+- zypper: name=nmap state=present
+
+# Remove the "nmap" package
+- zypper: name=nmap state=absent
+'''
+
 # Function used for getting the name of a currently installed package.
 def get_current_name(m, name):
     cmd = '/bin/rpm -q --qf \'%{NAME}-%{VERSION}\''