Merge pull request #2547 from jsmartin/cloudformation

Typo in cloudformation module documentation.

.gitignore

@@ -1,12 +1,31 @@
+# build products...
 *.py[co]
 build
+AUTHORS.TXT
 # Emacs backup files...
 *~
 .\#*
-# (s)rpm building stuff
+# RPM stuff...
 MANIFEST
 dist
 rpm-build
 # Eclipse/PyDev stuff...
 .project
 .pydevproject
+# PyCharm stuff...
+.idea
+# Mac OS X stuff...
+.DS_Store
+# manpage build stuff...
+docs/man/man3/*
+# Sublime stuff
+*.sublime-project
+*.sublime-workspace
+# docsite stuff...
+docsite/rst/modules
+docsite/*.html
+docsite/_static/*.gif
+docsite/_static/*.png
+docsite/_static/websupport.js
+# deb building stuff...
+debian/

CHANGELOG.md

@@ -1,7 +1,402 @@
 Ansible Changes By Release
 ==========================
 
-0.7 "Panama" -- release pending -- I can barely see the roadmap from the heat coming off of it.
+1.1 "Mean Street" -- Release pending
+
+Core Features
+
+* added --check option for "dry run" mode
+* added --diff option to show how templates or copied files change, or might change
+* --list-tasks for the playbook will list the tasks without running them
+* able to set the environment by setting "environment:" as a dictionary on any task (go proxy support!)
+* added ansible_ssh_user and ansible_ssh_pass for per-host/group username and password
+* jinja2 extensions can now be loaded from the config file
+* support for complex arguments to modules (within reason)
+* can specify ansible_connection=X to define the connection type in inventory variables
+* a new chroot connection type
+* module common code now has basic type checking (and casting) capability 
+* module common now supports a 'no_log' attribute to mark a field as not to be syslogged
+* inventory can now point to a directory containing multiple scripts/hosts files, if using this, put group_vars/host_vars directories inside this directory
+* added configurable crypt scheme for 'vars_prompt'
+* password generating lookup plugin -- $PASSWORD(path/to/save/data/in)
+* added --step option to ansible-playbook, works just like Linux interactive startup!
+
+Modules Added:
+
+* bzr (bazaar version control)
+* cloudformation
+* django-manage
+* gem (ruby gems)
+* homebrew
+* lvg (logical volume groups)
+* lvol (LVM logical volumes)
+* macports
+* mongodb_user
+* netscaler
+* okg
+* openbsd_pkg
+* rabbit_mq_plugin
+* rabbit_mq_user
+* rabbit_mq_vhost
+* rabbit_mq_parameter
+* rhn_channel
+* s3 -- allows putting file contents in buckets for sharing over s3
+* uri module -- can get/put/post/etc
+* vagrant -- launching VMs with vagrant, this is different from existing vagrant plugin
+* zfs
+
+Bugfixes and Misc Changes:
+
+* stderr shown when commands fail to parse
+* uses yaml.safe_dump in filter plugins
+* authentication Q&A no longer happens before --syntax-check, but after
+* ability to get hostvars data for nodes not in the setup cache yet
+* SSH timeout now correctly passed to native SSH connection plugin
+* raise an error when multiple when_ statements are provided
+* --list-hosts applies host limit selections better
+* (internals) template engine specifications to use template_ds everywhere
+* better error message when your host file can not be found
+* end of line comments now work in the inventory file
+* directory destinations now work better with remote md5 code
+* lookup plugin macros like $FILE and $ENV now work without returning arrays in variable definitions/playbooks
+* uses yaml.safe_load everywhere
+* able to add EXAMPLES to documentation via EXAMPLES docstring, rather than just in main documentation YAML
+* can set ANSIBLE_COW_SELECTION to pick other cowsay types (including random)
+* to_nice_yaml and to_nice_json available as Jinja2 filters that indent and sort
+* cowsay able to run out of macports (very important!)
+* improved logging for fireball mode
+* nicer error message when talking to an older system that needs a JSON module installed
+* 'magic' variable 'inventory_basedir' now gives path to inventory file
+* 'magic' variable 'vars' works like 'hostvars' but gives global scope variables, useful for debugging in templates mostly
+* conditionals can be used on plugins like add_host
+* developers: all callbacks now have access to a ".runner" and ".playbook", ".play", and ".task" object (use getattr, they may not always be set!)
+
+Facts:
+
+* block device facts for the setup module
+* facts for AIX
+* fact detection for OS type on Amazon Linux
+* device fact gathering stability improvements
+* ansible_os_family fact added
+* user_id (remote user name)
+* a whole series of current time information under the 'datetime' hash
+* more OS X facts
+* support for detecting Alpine Linux
+* added facts for OpenBSD
+
+Module Changes/Fixes:
+
+* ansible module common code (and ONLY that) which is mixed in with modules, is now BSD licensed.  App remains GPLv3.
+* service code works better on platforms that mix upstart, systemd, and system-v
+* service enablement idempotence fixes for systemd and upstart
+* service status 4 is also 'not running'
+* supervisorctl restart fix
+* increased error handling for ec2 module
+* can recursively set permissions on directories
+* ec2: change to the way AMI tags are handled
+* cron module can now also manipulate cron.d files
+* virtualenv module can now inherit system site packages (or not)
+* lineinfile module now has an insertbefore option
+* NetBSD service module support
+* fixes to sysctl module where item has multiple values
+* AIX support for the user and group modules
+* able to specify a different hg repo to pull from than the original set
+* add_host module can set ports and other inventory variables
+* add_host module can add modules to multiple groups (groups=a,b,c), groups now alias for groupname
+* subnet ID can be set on EC2 module
+* MySQL module password handling improvements
+* added new virtualenv flags to pip and easy_install modules
+* various improvements to lineinfile module, now accepts common arguments from file
+* force= now replaces thirsty where used before, thirsty remains an alias
+* setup module can take a 'filter=<wildcard>' parameter to just return a few facts (not used by playbooks)
+* cron module works even if no crontab is present (for cron.d)
+* security group ID settable on EC2 module
+* misc fixes to sysctl module
+* fix to apt module so packages not in cache are still removable
+* charset fix to mail module
+* postresql db module now does not try to create the 'PUBLIC' user
+* SVN module now works correctly with self signed certs
+* apt module now has an upgrade parameter (values=yes, no, or 'dist')
+* nagios module gets new silence/unsilence commands
+* ability to disable proxy usage in get_url (use_proxy=no)
+* more OS X facts
+* added a 'fail_on_missing' (default no) option to fetch
+* added timeout to the uri module (default 30 seconds, adjustable)
+* ec2 now has a 'wait' parameter to wait for the instance to be active, eliminates need for seperate wait_for call.
+* allow regex backreferences in lineinfile
+* id attribute on ec2 module can be used to set idempotent-do-not-recreate launches
+* icinga support for nagios module
+* fix default logins when no my.conf for MySQL module
+* option to create users with non-unique UIDs (user module)
+* macports module can enable/disable packages
+* quotes in my.cnf are stripped by the MySQL modules
+* Solaris Service management added
+* service module will attempt to auto-add unmanaged chkconfig services when needed
+* service module supports systemd service unit files
+
+Plugins:
+
+* added 'with_random_choice' filter plugin
+* fixed ~ expansion for fileglob
+* with_nested allows for nested loops (see examples in examples/playbooks)
+
+1.0 "Eruption" -- Feb 1 2013
+
+New modules:
+
+* new sysctl module
+* new pacman module (Arch linux)
+* new apt_key module
+* hg module now in core
+* new ec2_facts module
+* added pkgin module for Joyent SmartOS
+
+New config settings:
+
+* sudo_exe parameter can be set in config to use sudo alternatives
+* sudo_flags parameter can alter the flags used with sudo
+
+New playbook/language features:
+
+* added when_failed and when_changed
+* task includes can now be of infinite depth
+* when_set and when_unset can take more than one var (when_set: $a and $b and $c)
+* added the with_sequence lookup plugin
+* can override "connection:" on an indvidual task
+* parameterized playbook includes can now define complex variables (not just all on one line)
+* making inventory variables available for use in vars_files paths
+* messages when skipping plays are now more clear
+* --extra-vars now has maximum precedence (as intended)
+
+Module fixes and new flags:
+
+* ability to use raw module without python on remote system
+* fix for service status checking on Ubuntu
+* service module now responds to additional exit code for SERVICE_UNAVAILABLE
+* fix for raw module with '-c local'
+* various fixes to git module
+* ec2 module now reports the public DNS name
+* can pass executable= to the raw module to specify alternative shells
+* fix for postgres module when user contains a "-"
+* added additional template variables -- $template_fullpath and $template_run_date
+* raise errors on invalid arguments used with a task include statement
+* shell/command module takes a executable= parameter to specify a different shell than /bin/sh
+* added return code and error output to the raw module
+* added support for @reboot to the cron module
+* misc fixes to the pip module
+* nagios module can schedule downtime for all services on the host
+* various subversion module improvements
+* various mail module improvements
+* SELinux fix for files created by authorized_key module
+* "template override" ??
+* get_url module can now send user/password authorization
+* ec2 module can now deploy multiple simultaneous instances
+* fix for apt_key modules stalling in some situations
+* fix to enable Jinja2 {% include %} to work again in template
+* ec2 module is now powered by Boto
+* setup module can now detect if package manager is using pacman
+* fix for yum module with enablerepo in use on EL 6
+
+Core fixes and new behaviors:
+
+* various fixes for variable resolution in playbooks
+* fixes for handling of "~" in some paths
+* various fixes to DWIM'ing of relative paths
+* /bin/ansible now takes a --list-hosts just like ansible-playbook did
+* various patterns can now take a regex vs a glob if they start with "~" (need docs on which!) - also /usr/bin/ansible
+* allow intersecting host patterns by using "&" ("webservers:!debian:&datacenter1")
+* handle tilde shell character for --private-key
+* hash merging policy is now selectable in the config file, can choose to override or merge
+* environment variables now available for setting all plugin paths (ANSIBLE_CALLBACK_PLUGINS, etc)
+* added packaging file for macports (not upstreamed yet)
+* hacking/test-module script now uses /usr/bin/env properly
+* fixed error formatting for certain classes of playbook syntax errors
+* fix for processing returns with large volumes of output
+
+Inventory files/scripts:
+
+* hostname patterns in the inventory file can now use alphabetic ranges
+* whitespace is now allowed around group variables in the inventory file
+* inventory scripts can now define groups of groups and group vars (need example for docs?)
+
+0.9 "Dreams" -- Nov 30 2012
+
+Highlighted core changes:
+
+* various performance tweaks, ansible executes dramatically less SSH ops per unit of work
+* close paramiko SFTP connections less often on copy/template operations (speed increase)
+* change the way we use multiprocessing (speed/RAM usage improvements)
+* able to set default for asking password & sudo password in config file
+* ansible now installs nicely if running inside a virtualenv
+* flag to allow SSH connection to move files by scp vs sftp (in config file)
+* additional RPM subpackages for easily installing fireball mode deps (server and node)
+* group_vars/host_vars now available to ansible, not just playbooks
+* native ssh connection type (-c ssh) now supports passwords as well as keys
+* ansible-doc program to show details
+
+Other core changes:
+
+* fix for template calls when last character is '$'
+* if ansible_python_interpreter is set on a delegated host, it now works as intended
+* --limit can now take "," as separator as well as ";" or ":"
+* msg is now displaced with newlines when a task fails
+* if any with_ plugin has no results in a list (empty list for with_items, etc), the task is now skipped
+* various output formatting fixes/improvements
+* fix for Xen dom0/domU detection in default facts
+* 'ansible_domain' fact now available (ex value: example.com)
+* configured remote temp file location is now always used even for root
+* 'register'-ed variables are not recorded for skipped hosts (for example, using only_if/when)
+* duplicate host records for the same host can no longer result when a host is listed in multiple groups
+* ansible-pull now passes --limit to prevent running on multiple hosts when used with generic playbooks
+* remote md5sum check fixes for Solaris 10
+* ability to configure syslog facility used by remote module calls
+* in templating, stray '$' characters are now handled more correctly
+
+Playbook changes:
+
+* relative paths now work for 'first_available_file'
+* various templating engine fixes
+* 'when' is an easier form of only if
+* --list-hosts on the playbook command now supports multiple playbooks on the same command line
+* playbook includes can now be parameterized
+
+Module additions:
+
+* (addhost) new module for adding a temporary host record (used for creating new guests)
+* (group_by) module allows partitioning hosts based on group data
+* (ec2) new module for creating ec2 hosts
+* (script) added 'script' module for pushing and running self-deleting remote scripts
+* (svr4pkg) solaris svr4pkg module
+
+Module changes:
+
+* (authorized key) module uses temp file now to prevent failure on full disk
+* (fetch) now uses the 'slurp' internal code to work as you would expect under sudo'ed accounts
+* (fetch) internal usage of md5 sums fixed for BSD
+* (get_url) thirsty is no longer required for directory destinations
+* (git) various git module improvements/tweaks
+* (group) now subclassed for various platforms, includes SunOS support
+* (lineinfile) create= option on lineinfile can create the file when it does not exist
+* (mysql_db) module takes new grant options
+* (postgresql_db) module now takes role_attr_flags
+* (service) further upgrades to service module service status reporting
+* (service) tweaks to get service module to play nice with BSD style service systems (rc.conf)
+* (service) possible to pass additional arguments to services
+* (shell) and command module now take an 'executable=' flag for specifying an alternate shell than /bin/sh
+* (user) ability to create SSH keys for users when using user module to create users
+* (user) atomic replacement of files preserves permissions of original file
+* (user) module can create SSH keys
+* (user) module now does Solaris and BSD
+* (yum) module takes enablerepo= and disablerepo=
+* (yum) misc yum module fixing for various corner cases
+
+Plugin changes:
+
+* EC2 inventory script now produces nicer failure message if AWS is down (or similar)
+* plugin loading code now more streamlined
+* lookup plugins for DNS text records, environment variables, and redis
+* added a template lookup plugin $TEMPLATE('filename.j2')
+* various tweaks to the EC2 inventory plugin 
+* jinja2 filters are now pluggable so it's easy to write your own (to_json/etc, are now impl. as such)
+
+0.8 "Cathedral" -- Oct 19, 2012
+
+Highlighted Core Changes:
+
+* fireball mode -- ansible can bootstrap a ephemeral 0mq (zeromq) daemon that runs as a given user and expires after X period of time.  It is very fast.
+* playbooks with errors now return 2 on failure.  1 indicates a more fatal syntax error.  Similar for /usr/bin/ansible
+* server side action code (template, etc) are now fully pluggable
+* ability to write lookup plugins, like the code powering "with_fileglob" (see below)
+
+Other Core Changes:
+
+* ansible config file can also go in '.ansible.cfg' in cwd in addition to ~/.ansible.cfg and /etc/ansible/ansible.cfg
+* fix for inventory hosts at API level when hosts spec is a list and not a colon delimited string
+* ansible-pull example now sets up logrotate for the ansible-pull cron job log
+* negative host matching (!hosts) fixed for external inventory script usage
+* internals: os.executable check replaced with utils function so it plays nice on AIX
+* Debian packaging now includes ansible-pull manpage
+* magic variable 'ansible_ssh_host' can override the hostname (great for usage with tunnels)
+* date command usage in build scripts fixed for OS X
+* don't use SSH agent with paramiko if a password is specified
+* make output be cleaner on multi-line command/shell errors
+* /usr/bin/ansible now prints things when tasks are skipped, like when creates= is used with -m command and /usr/bin/ansible
+* when trying to async a module that is not a 'normal' asyncable module, ansible will now let you know
+* ability to access inventory variables via 'hostvars' for hosts not yet included in any play, using on demand lookups
+* merged ansible-plugins, ansible-resources, and ansible-docs into the main project
+* you can set ANSIBLE_NOCOWS=1 if you want to disable cowsay if it is installed.  Though no one should ever want to do this!  Cows are great!
+* you can set ANSIBLE_FORCECOLOR=1 to force color mode even when running without a TTY
+* fatal errors are now properly colored red.
+* skipped messages are now cyan, to differentiate them from unchanged messages.
+* extensive documentation upgrades
+* delegate_action to localhost (aka local_action) will always use the local connection type
+
+Highlighted playbook changes:
+
+* is_set is available for use inside of an only_if expression:  is_set('ansible_eth0').  We intend to further upgrade this with a 'when'
+  keyword providing better options to 'only_if' in the next release.   Also is_unset('ansible_eth0')
+* playbooks can import playbooks in other directories and then be able to import tasks relative to them
+* FILE($path) now allows access of contents of file in a path, very good for use with SSH keys
+* similarly PIPE($command) will run a local command and return the results of executing this command
+* if all hosts in a play fail, stop the playbook, rather than letting the console log spool on by
+* only_if using register variables that are booleans now works in a boolean way like you'd expect
+* task includes now work with with_items (such as: include: path/to/wordpress.yml user=$item)
+* when using a $list variable with $var or ${var} syntax it will automatically join with commas
+* setup is not run more than once when we know it is has already been run in a play that included another play, etc
+* can set/override sudo and sudo_user on individual tasks in a play, defaults to what is set in the play if not present
+* ability to use with_fileglob to iterate over local file patterns
+* templates now use Jinja2's 'trim_blocks=True' to avoid stray newlines, small changes to templates may
+be required in rare cases.
+
+Other playbook changes:
+
+* to_yaml and from_yaml are available as Jinja2 filters
+* $group and $group_names are now accessible in with_items
+* where 'stdout' is provided a new 'stdout_lines' variable (type == list) is now generated and usable with with_items
+* when local_action is used the transport is automatically overridden to the local type
+* output on failed playbook commands is now nicely split for stderr/stdout and syntax errors
+* if local_action is not used and delegate_to was 127.0.0.1 or localhost, use local connection regardless
+* when running a playbook, and the statement has changed, prints 'changed:' now versus 'ok:' so it is obvious without colored mode
+* variables now usable within vars_prompt (just not host/group vars)
+* setup facts are now retained across plays (dictionary just gets updated as needed)
+* --sudo-user now works with --extra-vars
+* fix for multi_line strings with only_if
+
+New Modules:
+
+* ini_file module for manipulating INI files
+* new LSB facts (release, distro, etc)
+* pause module -- (pause seconds=10) (pause minutes=1) (pause prompt=foo) -- it's an action plugin
+* a module for adding entries to the main crontab (though you may still wish to just drop template files into cron.d)
+* debug module can be used for outputing messages without using 'shell echo'
+* a fail module is now available for causing errors, you might want to use it with only_if to fail in certain conditions
+
+Other module Changes, Upgrades, and Fixes:
+
+* removes= exists on command just like creates=
+* postgresql modules now take an optional port= parameter
+* /proc/cmdline info is now available in Linux facts
+* public host key detection for OS X
+* lineinfile module now uses 'search' not exact 'match' in regexes, making it much more intuitive and not needing regex syntax most of the time
+* added force=yes|no (default no) option for file module, which allows transition between files to directories and so on
+* additional facts for SunOS virtualization
+* copy module is now atomic when used across volumes
+* url_get module now returns 'dest' with the location of the file saved
+* fix for yum module when using local RPMs vs downloading
+* cleaner error messages with copy if destination directory does not exist
+* setup module now still works if PATH is not set
+* service module status now correct for services with 'subsys locked' status
+* misc fixes/upgrades to the wait_for module
+* git module now expands any "~" in provided destination paths
+* ignore stop error code failure for service module with state=restarted, always try to start
+* inline documentation for modules allows documentation source to built without pull requests to the ansible-docs project, among other things
+* variable '$ansible_managed' is now great to include at the top of your templates and includes useful information and a warning that it will be replaced
+* "~" now expanded in command module when using creates/removes
+* mysql module can do dumps and imports
+* selinux policy is only required if setting to not disabled
+* various fixes for yum module when working with packages not in any present repo
+
+0.7 "Panama" -- Sept 6 2012
 
 Module changes:
 
@@ -75,13 +470,13 @@ playbooks:
 * error reporting if with_items value is unbound
 * with_items no longer creates lots of tasks, creates one task that makes multiple calls
 * can use host_specific facts inside with_items (see above)
-* at the top level of a playbook, set 'gather_facts: False' to skip fact gathering
+* at the top level of a playbook, set 'gather_facts: no' to skip fact gathering
 * first_available_file and with_items used together will now raise an error
 * to catch typos, like 'var' for 'vars', playbooks and tasks now yell on invalid parameters
 * automatically load (directory_of_inventory_file)/group_vars/groupname and /host_vars/hostname in vars_files
 * playbook is now colorized, set ANSIBLE_NOCOLOR=1 if you do not like this, does not colorize if not a TTY
 * hostvars now preserved between plays (regression in 0.5 from 0.4), useful for sharing vars in multinode configs
-* ignore_errors: True on a task can be used to allow a task to fail and not stop the play
+* ignore_errors: yes on a task can be used to allow a task to fail and not stop the play
 * with_items with the apt/yum module will install/remove/update everything in a single command
 
 inventory:
@@ -140,7 +535,7 @@ internals:
 * support for older versions of python-apt in the apt module
 * a new "assemble" module, for constructing files from pieces of files (inspired by Puppet "fragments" idiom)
 * ability to override most default values with ANSIBLE_FOO environment variables
-* --module-path parameter can support multiple directories seperated with the OS path seperator
+* --module-path parameter can support multiple directories separated with the OS path separator
 * with_items can take a variable of type list
 * ansible_python_interpreter variable available for systems with more than one Python
 * BIOS and VMware "fact" upgrades

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+Contributing to Ansible
+=======================
+
+It is required that you read the following information to learn how to contribute to this project.
+
+Branch Info
+===========
+
+Here's how to understand the branches.
+
+   * The devel branch corresponds to the latest ongoing release
+   * Various release-X.Y branches exist for previous releases
+   * All feature work happens on the development branch.
+   * Major bug fixes will be made to the last release branch only
+   * See CHANGELOG.md for release notes to track each release.
+
+Patch Instructions
+==================
+
+Contributions to the core and modules are greatly welcome.
+
+   * Required Process:
+       * Submit github pull requests to the "ansible/devel" branch for features
+       * Fixes for bugs may also be submitted to "ansible/release-X.Y" for the last release
+       * Make sure "make tests" passes before submitting any requests.
+   * Bonus points:
+       * Joining the mailing list
+       * Fixing bugs instead of sending bug reports.
+       * Using squash merges
+       * Updating the "rst/*" files in the "docsite/" directory and "docs/" manpage content
+       * Adding more unit tests
+   * Avoid:
+       * Sending patches to the mailing list directly.
+       * Sending feature pull requests to the 'release' branch instead of the devel branch
+       * Sending pull requests to mpdehaan's personal ansible fork.
+       * Sending pull requests about more than one feature in the same pull request.
+       * Whitespace restructuring
+       * Large scale refactoring without a discussion on the list
+
+Coding Standards
+================
+
+We're not too strict on style considerations, but we require:
+
+   * python 2.6 compliant code, unless in ansible modules, then python *2.4* compliant code (no 'with', etc)
+   * 4-space indents, no tabs except in Makefiles
+   * under_scores for method names and variables, not camelCase
+   * GPLv3 license headers on all files, with copyright on new files with your name on it
+   * no single-line if statements, deeply nested list comprehensions, or clever use of metaclasses -- keep it simple
+   * comments where appropriate
+
+Testing Requirements
+====================
+
+Automation tests are run by "make tests" and contain a mixture of integration and "unit" level tests.  To run the tests you need the following:
+
+   * nose must be installed - https://nose.readthedocs.org/en/latest/
+   * ansible tests require paramiko, PyYAML python modules, and python 2.6+.
+   * Some tests require additional components (facter, ohai) and will be skipped if not available.
+   * Your user environment should allow "ssh 127.0.0.1"
+     without a password - so a key held in ssh-agent and an authorized_keys entry.
+
+If your module does not require any additional dependencies beyond ansible-core, it is a good idea to write some
+tests for the module.
+
+Contributors License Agreement
+==============================
+
+By contributing you agree that these contributions are your own (or approved by your employer) and you grant a full, complete, irrevocable
+copyright license to all users and developers of the project, present and future, persusant to the license of the project.
+
+
+

Makefile

@@ -9,7 +9,7 @@
 #   make deb ------------------ produce a DEB
 #   make docs ----------------- rebuild the manpages (results are checked in)
 #   make tests ---------------- run the tests
-#   make pyflakes, make pep8 -- source code checks  
+#   make pyflakes, make pep8 -- source code checks
 
 ########################################################
 # variable section
@@ -20,16 +20,21 @@ OS = $(shell uname -s)
 # Manpages are currently built with asciidoc -- would like to move to markdown
 # This doesn't evaluate until it's called. The -D argument is the
 # directory of the target file ($@), kinda like `dirname`.
+MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1 docs/man/man1/ansible-doc.1
+ifneq ($(shell which a2x 2>/dev/null),)
 ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $<
 ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml
-MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1
+else
+ASCII2MAN = @echo "ERROR: AsciiDoc 'a2x' command is not installed but is required to build $(MANPAGES)" && exit 1
+endif
 
-SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
+PYTHON=python
+SITELIB = $(shell $(PYTHON) -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
 
 # VERSION file provides one place to update the software version
 VERSION := $(shell cat VERSION)
 
-### Get the branch information from git
+# Get the branch information from git
 ifneq ($(shell which git),)
 GIT_DATE := $(shell git log -n 1 --format="%ai")
 endif
@@ -37,7 +42,11 @@ endif
 ifeq ($(OS), FreeBSD)
 DATE := $(shell date -j -f "%Y-%m-%d %H:%M:%s"  "$(GIT_DATE)" +%Y%m%d%H%M)
 else
-DATE := $(shell date --date="$(GIT_DATE)" +%Y%m%d%H%M)
+ifeq ($(OS), Darwin)
+DATE := $(shell date -j -f "%Y-%m-%d %H:%M:%S"  "$(GIT_DATE)" +%Y%m%d%H%M)
+else
+DATE := $(shell date --utc --date="$(GIT_DATE)" +%Y%m%d%H%M)
+endif
 endif
 
 # RPM build parameters
@@ -54,11 +63,14 @@ RPMNVR = "$(NAME)-$(VERSION)-$(RPMRELEASE)$(RPMDIST)"
 
 all: clean python
 
-tests: 
-	PYTHONPATH=./lib nosetests -v
+tests:
+	PYTHONPATH=./lib nosetests -d -v
 
 # To force a rebuild of the docs run 'touch VERSION && make docs'
-docs: $(MANPAGES)
+docs: $(MANPAGES) modulepages
+
+authors:
+	sh hacking/authors.sh
 
 # Regenerate %.1.asciidoc if %.1.asciidoc.in has been modified more
 # recently than %.1.asciidoc.
@@ -92,9 +104,10 @@ clean:
 	@echo "Cleaning up editor backup files"
 	find . -type f \( -name "*~" -or -name "#*" \) -delete
 	find . -type f \( -name "*.swp" \) -delete
-	@echo "Cleaning up asciidoc to man transformations and results"
+	@echo "Cleaning up manpage stuff"
 	find ./docs/man -type f -name "*.xml" -delete
 	find ./docs/man -type f -name "*.asciidoc" -delete
+	find ./docs/man/man3 -type f -name "*.3" -delete
 	@echo "Cleaning up output from test runs"
 	rm -rf test/test_data
 	@echo "Cleaning up RPM building stuff"
@@ -102,15 +115,19 @@ clean:
 	@echo "Cleaning up Debian building stuff"
 	rm -rf debian
 	rm -rf deb-build
+	rm -rf docs/json
+	rm -rf docs/js
+	@echo "Cleaning up authors file"
+	rm -f AUTHORS.TXT
 
 python:
-	python setup.py build
+	$(PYTHON) setup.py build
 
 install:
-	python setup.py install
+	$(PYTHON) setup.py install
 
-sdist: clean
-	python setup.py sdist -t MANIFEST.in
+sdist: clean docs
+	$(PYTHON) setup.py sdist -t MANIFEST.in
 
 rpmcommon: sdist
 	@mkdir -p rpm-build
@@ -138,7 +155,8 @@ rpm: rpmcommon
 	--define "_srcrpmdir %{_topdir}" \
 	--define "_specdir $(RPMSPECDIR)" \
 	--define "_sourcedir %{_topdir}" \
-	--define "_rpmfilename $(RPMNVR).%%{ARCH}.rpm" \
+	--define "_rpmfilename %%{NAME}-%%{VERSION}-%%{RELEASE}.%%{ARCH}.rpm" \
+	--define "__python `which $(PYTHON)`" \
 	-ba rpm-build/$(NAME).spec
 	@rm -f rpm-build/$(NAME).spec
 	@echo "#############################################"
@@ -156,3 +174,23 @@ deb: debian
 
 # for arch or gentoo, read instructions in the appropriate 'packaging' subdirectory directory
 
+modulepages:
+	PYTHONPATH=./lib $(PYTHON) hacking/module_formatter.py -A $(VERSION) -t man -o docs/man/man3/ --module-dir=library --template-dir=hacking/templates
+
+modulejson:
+	mkdir -p docs/json
+	PYTHONPATH=./lib $(PYTHON) hacking/module_formatter.py -A $(VERSION) -t json -o docs/json --module-dir=library --template-dir=hacking/templates
+
+modulejs:
+	mkdir -p docs/js
+	make modulejson
+	PYTHONPATH=./lib $(PYTHON) hacking/module_formatter.py -A $(VERSION) -t js -o docs/js --module-dir=docs/json --template-dir=hacking/templates
+
+# because this requires Sphinx it is not run as part of every build, those building the RPM and so on can ignore this
+
+webdocs:
+	(cd docsite; make docs)
+
+# just for quick testing of all the module docs
+webdocs2:
+	(cd docsite; make modules)

README.md

@@ -4,7 +4,11 @@ Ansible
 Ansible is a radically simple configuration-management, deployment, task-execution, and
 multinode orchestration framework.
 
-Read the documentation at http://ansible.github.com
+Read the documentation and more at http://ansible.cc
+
+Many users run straight from the development branch (it's generally fine to do so), but you might also wish to consume a release.  You can find 
+instructions on http://ansible.cc/docs/gettingstarted.html for a variety of platforms.  If you want a tarball of the last release, go to 
+http://ansible.cc/releases/ and you can also install with pip (though that will bring in some optional binary dependencies you normally do not need).
 
 Design Principles
 =================
@@ -28,32 +32,9 @@ Branch Info
 ===========
 
    * Releases are named after Van Halen songs.
-   * The devel branch corresponds to release 0.7, "Panama".
+   * The devel branch corresponds to the release actively under development.
    * Various release-X.Y branches exist for previous releases
-   * All feature work happens on the development branch.
-   * Major bug fixes will be made to the last release branch only
-   * See CHANGELOG.md for release notes to track each release.
-
-Patch Instructions
-==================
-
-Contributions to the core and modules are greatly welcome.
-
-   * Required Process:
-       * Submit github pull requests to the "ansible/devel" branch for features
-       * Fixes for bugs may also be submitted to "ansible/release-X.Y" for the last release
-       * Make sure "make tests" passes before submitting any requests.
-   * Bonus points:
-       * Joining the mailing list
-       * Fixing bugs instead of sending bug reports.
-       * Using squash merges
-       * Updating the "rst/*" files in the docs project and "docs/" manpage content
-       * Adding more unit tests
-   * Avoid:
-       * Sending patches to the mailing list directly.
-       * Sending feature pull requests to the 'release' branch instead of the devel branch
-       * Sending pull requests to mpdehaan's personal ansible fork.
-
+   * We'd love to have your contributions, read "CONTRIBUTING.md" for process notes.
 
 Author
 ======

RELEASES.txt

@@ -1,11 +1,15 @@
 Ansible Releases at a Glance
 ============================
 
-0.7 "Panama" ---------- X-XX-2012
-0.6 "Cabo" ------------ 8-06-2012
-0.5 "Amsterdam" ------- 7-04-2012
-0.4 "Unchained" ------- 5-23-2012
-0.3 "Baluchitherium" -- 4-23-2012
+1.1 "Mean Street" ----- pending 
+1.0 "Eruption" -------- 02-01-2013
+0.9 "Dreams" ---------- 11-30-2012
+0.8 "Cathedral" ------- 10-19-2012
+0.7 "Panama" ---------- 09-06-2012
+0.6 "Cabo" ------------ 08-06-2012
+0.5 "Amsterdam" ------- 07-04-2012
+0.4 "Unchained" ------- 05-23-2012
+0.3 "Baluchitherium" -- 04-23-2012
 0.0.2 Untitled
 0.0.1 Untitled
 

VERSION

@@ -1 +1 @@
-0.7
+1.1

bin/ansible

@@ -45,13 +45,26 @@ class Cli(object):
     def parse(self):
         ''' create an options parser for bin/ansible '''
 
-        parser = utils.base_parser(constants=C, runas_opts=True, subset_opts=True, async_opts=True,
-            output_opts=True, connect_opts=True, usage='%prog <host-pattern> [options]')
+        parser = utils.base_parser(
+            constants=C, 
+            runas_opts=True, 
+            subset_opts=True, 
+            async_opts=True,
+            output_opts=True, 
+            connect_opts=True, 
+            check_opts=True,
+            diff_opts=False,
+            usage='%prog <host-pattern> [options]'
+        )
+
         parser.add_option('-a', '--args', dest='module_args',
             help="module arguments", default=C.DEFAULT_MODULE_ARGS)
         parser.add_option('-m', '--module-name', dest='module_name',
             help="module name to execute (default=%s)" % C.DEFAULT_MODULE_NAME,
             default=C.DEFAULT_MODULE_NAME)
+        parser.add_option('--list-hosts', dest='listhosts', action='store_true',
+            help="dump out a list of hosts matching input pattern, does not execute any modules!")
+
         options, args = parser.parse_args()
         self.callbacks.options = options
 
@@ -68,15 +81,28 @@ class Cli(object):
         pattern = args[0]
 
         inventory_manager = inventory.Inventory(options.inventory)
+        if options.subset:
+            inventory_manager.subset(options.subset)
         hosts = inventory_manager.list_hosts(pattern)
         if len(hosts) == 0:
             print >>sys.stderr, "No hosts matched"
             sys.exit(1)
 
+        if options.listhosts:
+            for host in hosts:
+                print '    %s' % host
+            sys.exit(0)
+
+        if options.module_name == 'command' and not options.module_args:
+            print >>sys.stderr, "No argument passed to command module"
+            sys.exit(1)
+
         sshpass = None
         sudopass = None
+        options.ask_pass = options.ask_pass or C.DEFAULT_ASK_PASS
         if options.ask_pass:
             sshpass = getpass.getpass(prompt="SSH password: ")
+        options.ask_sudo_pass= options.ask_sudo_pass or C.DEFAULT_ASK_SUDO_PASS
         if options.ask_sudo_pass:
             sudopass = getpass.getpass(prompt="sudo password: ")
             options.sudo = True
@@ -96,7 +122,9 @@ class Cli(object):
             pattern=pattern,
             callbacks=self.callbacks, sudo=options.sudo,
             sudo_pass=sudopass,sudo_user=options.sudo_user,
-            transport=options.connection, subset=options.subset
+            transport=options.connection, subset=options.subset,
+            check=options.check,
+            diff=options.check
         )
 
         if options.seconds:
@@ -127,6 +155,11 @@ if __name__ == '__main__':
     (options, args) = cli.parse()
     try:
         (runner, results) = cli.run(options, args)
+        for result in results['contacted'].values():
+            if 'failed' in result or result.get('rc', 0) != 0:
+                sys.exit(2)
+        if results['dark']:
+            sys.exit(2)
     except errors.AnsibleError, e:
         # Generic handler for ansible specific errors
         print "ERROR: %s" % str(e)

bin/ansible-doc

@@ -0,0 +1,215 @@
+#!/usr/bin/env python
+
+# (c) 2012, Jan-Piet Mens <jpmens () gmail.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+import os
+import sys
+import textwrap
+import re
+import optparse
+import datetime
+from ansible import utils
+from ansible.utils import module_docs
+import ansible.constants as C
+from ansible.utils import version
+import traceback
+
+MODULEDIR = C.DEFAULT_MODULE_PATH
+
+BLACKLIST_EXTS = ('.swp', '.bak', '~', '.rpm')
+
+_ITALIC = re.compile(r"I\(([^)]+)\)")
+_BOLD   = re.compile(r"B\(([^)]+)\)")
+_MODULE = re.compile(r"M\(([^)]+)\)")
+_URL    = re.compile(r"U\(([^)]+)\)")
+_CONST  = re.compile(r"C\(([^)]+)\)")
+
+def tty_ify(text):
+
+    t = _ITALIC.sub("`" + r"\1" + "'", text)    # I(word) => `word'
+    t = _BOLD.sub("*" + r"\1" + "*", t)         # B(word) => *word*
+    t = _MODULE.sub("[" + r"\1" + "]", t)       # M(word) => [word]
+    t = _URL.sub(r"\1", t)                      # U(word) => word
+    t = _CONST.sub("`" + r"\1" + "'", t)        # C(word) => `word'
+
+    return t
+
+def print_man(doc):
+
+    opt_indent="        "
+    print "> %s\n" % doc['module'].upper()
+
+    desc = "".join(doc['description'])
+
+    print "%s\n" % textwrap.fill(tty_ify(desc), initial_indent="  ", subsequent_indent="  ")
+    
+    if 'option_keys' in doc and len(doc['option_keys']) > 0:
+        print "Options (= is mandatory):\n"
+
+    for o in doc['option_keys']:
+        opt = doc['options'][o]
+
+        if opt.get('required', False):
+            opt_leadin = "="
+        else:
+            opt_leadin = "-"
+
+        print "%s %s" % (opt_leadin, o)
+
+        desc = "".join(opt['description'])
+
+        if 'choices' in opt:
+            choices = ", ".join(str(i) for i in opt['choices'])
+            desc = desc + " (Choices: " + choices + ")"
+        print "%s\n" % textwrap.fill(tty_ify(desc), initial_indent=opt_indent,
+                            subsequent_indent=opt_indent)
+
+    if 'notes' in doc and len(doc['notes']) > 0:
+        notes = "".join(doc['notes'])
+        print "Notes:%s\n" % textwrap.fill(tty_ify(notes), initial_indent="  ",
+                            subsequent_indent=opt_indent)
+
+
+    if 'examples' in doc and len(doc['examples']) > 0:
+        print "Example%s:\n" % ('' if len(doc['examples']) < 2 else 's')
+        for ex in doc['examples']:
+            print "%s\n" % (ex['code'])
+
+    if 'plainexamples' in doc and doc['plainexamples'] is not None:
+        print doc['plainexamples']
+
+def print_snippet(doc):
+
+    desc = tty_ify("".join(doc['short_description']))
+    print "- name: %s" % (desc)
+    print "  action: %s" % (doc['module'])
+
+    for o in doc['options']:
+        opt = doc['options'][o]
+        desc = tty_ify("".join(opt['description']))
+        s = o + "="
+        print "      %-20s   # %s" % (s, desc)
+
+def main():
+
+    p = optparse.OptionParser(
+        version=version("%prog"),
+        usage='usage: %prog [options] [module...]',
+        description='Show Ansible module documentation',
+    )
+
+    p.add_option("-M", "--module-path",
+            action="store",
+            dest="module_path",
+            default=MODULEDIR,
+            help="Ansible modules/ directory")
+    p.add_option("-l", "--list",
+            action="store_true",
+            default=False,
+            dest='list_dir',
+            help='List available modules')
+    p.add_option("-s", "--snippet",
+            action="store_true",
+            default=False,
+            dest='show_snippet',
+            help='Show playbook snippet for specified module(s)')
+    p.add_option('-v', action='version', help='Show version number and exit')
+
+    (options, args) = p.parse_args()
+
+    if options.module_path is not None:
+        for i in options.module_path.split(os.pathsep):
+            utils.plugins.module_finder.add_directory(i)
+
+    if options.list_dir:
+        # list all modules
+        paths = utils.plugins.module_finder._get_paths()
+        module_list = []
+        for path in paths:
+            # os.system("ls -C %s" % (path))
+            if os.path.isdir(path):
+                for module in os.listdir(path):
+                    if any(module.endswith(x) for x in BLACKLIST_EXTS):
+                        continue
+                    module_list.append(module)
+
+        for module in sorted(set(module_list)):
+
+            if module in module_docs.BLACKLIST_MODULES:
+                continue
+
+            filename = utils.plugins.module_finder.find_plugin(module)
+            try:
+                doc, plainexamples = module_docs.get_docstring(filename)
+                desc = tty_ify(doc.get('short_description', '?'))
+                if len(desc) > 55:
+                    desc = desc + '...'
+                print "%-20s %-60.60s" % (module, desc)
+            except:
+                traceback.print_exc()
+                sys.stderr.write("ERROR: module %s has a documentation error formatting or is missing documentation\n" % module)
+                pass
+
+        sys.exit()
+
+    if len(args) == 0:
+        p.print_help()
+    
+    for module in args:
+
+        filename = utils.plugins.module_finder.find_plugin(module)
+        if filename is None:
+            sys.stderr.write("module %s not found in %s\n" % (module,
+                    utils.plugins.module_finder.print_paths()))
+            continue
+
+        if any(filename.endswith(x) for x in BLACKLIST_EXTS):
+            continue
+
+        try:
+            doc, plainexamples = module_docs.get_docstring(filename)
+        except:
+            traceback.print_exc()
+            sys.stderr.write("ERROR: module %s has a documentation error formatting or is missing documentation\n" % module)
+            continue
+
+        if doc is not None:
+
+            all_keys = []
+            for (k,v) in doc['options'].iteritems():
+                all_keys.append(k)
+            all_keys = sorted(all_keys)
+            doc['option_keys'] = all_keys
+
+            doc['filename']         = filename
+            doc['docuri']           = doc['module'].replace('_', '-')
+            doc['now_date']         = datetime.date.today().strftime('%Y-%m-%d')
+            doc['plainexamples']    = plainexamples
+
+            if options.show_snippet:
+                print_snippet(doc)
+            else:
+                print_man(doc)
+        else:
+            # this typically means we couldn't even parse the docstring, not just that the YAML is busted,
+            # probably a quoting issue.
+            sys.stderr.write("ERROR: module %s missing documentation (or could not parse documentation)\n" % module)
+
+if __name__ == '__main__':
+    main()

bin/ansible-playbook

@@ -18,9 +18,9 @@
 
 #######################################################
 
-import os
 import sys
 import getpass
+import os
 
 import ansible.playbook
 import ansible.constants as C
@@ -52,13 +52,28 @@ def main(args):
 
     # create parser for CLI options
     usage = "%prog playbook.yml"
-    parser = utils.base_parser(constants=C, usage=usage, connect_opts=True, runas_opts=True, subset_opts=True)
+    parser = utils.base_parser(
+        constants=C, 
+        usage=usage, 
+        connect_opts=True, 
+        runas_opts=True, 
+        subset_opts=True, 
+        check_opts=True,
+        diff_opts=True
+    )
     parser.add_option('-e', '--extra-vars', dest="extra_vars", default=None,
         help="set additional key=value variables from the CLI")
     parser.add_option('-t', '--tags', dest='tags', default='all',
         help="only run plays and tasks tagged with these values")
+    # FIXME: list hosts is a common option and can be moved to utils/__init__.py
     parser.add_option('--list-hosts', dest='listhosts', action='store_true',
         help="dump out a list of hosts, each play will run against, does not run playbook!")
+    parser.add_option('--syntax-check', dest='syntax', action='store_true',
+        help="do a playbook syntax check on the playbook, do not execute the playbook")
+    parser.add_option('--list-tasks', dest='listtasks', action='store_true',
+        help="do list all tasks that would be executed")
+    parser.add_option('--step', dest='step', action='store_true',
+        help="one-step-at-a-time: confirm each task before running")
 
     options, args = parser.parse_args(args)
 
@@ -66,11 +81,18 @@ def main(args):
         parser.print_help(file=sys.stderr)
         return 1
 
+    inventory = ansible.inventory.Inventory(options.inventory)
+    inventory.subset(options.subset)
+    if len(inventory.list_hosts()) == 0:
+        raise errors.AnsibleError("provided hosts list is empty")
+
     sshpass = None
     sudopass = None
-    if not options.listhosts:
+    if not options.listhosts and not options.syntax and not options.listtasks:
+        options.ask_pass = options.ask_pass or C.DEFAULT_ASK_PASS
         if options.ask_pass:
             sshpass = getpass.getpass(prompt="SSH password: ")
+        options.ask_sudo_pass = options.ask_sudo_pass or C.DEFAULT_ASK_SUDO_PASS
         if options.ask_sudo_pass:
             sudopass = getpass.getpass(prompt="sudo password: ")
             options.sudo = True
@@ -80,17 +102,25 @@ def main(args):
     extra_vars = utils.parse_kv(options.extra_vars)
     only_tags = options.tags.split(",")
 
+    for playbook in args:
+        if not os.path.exists(playbook):
+            raise errors.AnsibleError("the playbook: %s could not be found" % playbook)
+        if not os.path.isfile(playbook):
+            raise errors.AnsibleError("the playbook: %s does not appear to be a file" % playbook)
+
     # run all playbooks specified on the command line
     for playbook in args:
 
         stats = callbacks.AggregateStats()
         playbook_cb = callbacks.PlaybookCallbacks(verbose=utils.VERBOSITY)
+        if options.step:
+            playbook_cb.step = options.step
         runner_cb = callbacks.PlaybookRunnerCallbacks(stats, verbose=utils.VERBOSITY)
 
         pb = ansible.playbook.PlayBook(
             playbook=playbook,
             module_path=options.module_path,
-            host_list=options.inventory,
+            inventory=inventory,
             forks=options.forks,
             remote_user=options.remote_user,
             remote_pass=sshpass,
@@ -105,26 +135,50 @@ def main(args):
             extra_vars=extra_vars,
             private_key_file=options.private_key_file,
             only_tags=only_tags,
-            subset=options.subset,
+            check=options.check,
+            diff=options.diff
         )
-        
-        if options.listhosts:
+
+        if options.listhosts or options.listtasks:
+            print ''
+            print 'playbook: %s' % playbook
+            print ''
             playnum = 0
-            for play in pb.playbook:
+            for (play_ds, play_basedir) in zip(pb.playbook, pb.play_basedirs):
                 playnum += 1
-                if 'hosts' in play:
-                    label = 'unnamed'
-                    if 'name' in play:
-                        label = play['name']
-                    print 'hosts in play %s: %s' % (playnum, label)
-                    for host in pb.inventory.list_hosts(play['hosts']):
-                        print '  %s' % host
-                    print '\n'
+                play = ansible.playbook.Play(pb, play_ds, play_basedir)
+                label = play.name
+                if options.listhosts:
+                    hosts = pb.inventory.list_hosts(play.hosts)
+                    print '  play #%d (%s): host count=%d' % (playnum, label, len(hosts))
+                    for host in hosts:
+                        print '    %s' % host
+                if options.listtasks:
+                    matched_tags, unmatched_tags = play.compare_tags(pb.only_tags)
+                    unmatched_tags.discard('all')
+                    unknown_tags = set(pb.only_tags) - (matched_tags | unmatched_tags)
+                    if unknown_tags:
+                        msg = 'tag(s) not found in playbook: %s.  possible values: %s'
+                        unknown = ','.join(sorted(unknown_tags))
+                        unmatched = ','.join(sorted(unmatched_tags))
+                        raise errors.AnsibleError(msg % (unknown, unmatched))
+                    print '  play #%d (%s): task count=%d' % (playnum, label, len(play.tasks()))
+                    for task in play.tasks():
+                        if set(task.tags).intersection(pb.only_tags):
+                            print '    %s' % task.name
+                print ''
+            continue
+
+        if options.syntax:
+            # if we've not exited by now then we are fine.
+            print 'Playbook Syntax is fine'
             return 0
             
+
         try:
 
             pb.run()
+
             hosts = sorted(pb.stats.processed.keys())
             print callbacks.banner("PLAY RECAP")
             playbook_cb.on_stats(pb.stats)
@@ -138,6 +192,10 @@ def main(args):
                     colorize('failed', t['failures'], 'red'))
 
             print "\n"
+            for h in hosts:
+                stats = pb.stats.summarize(h)
+                if stats['failures'] != 0 or stats['unreachable'] != 0:
+                    return 2
 
         except errors.AnsibleError, e:
             print >>sys.stderr, "ERROR: %s" % e

bin/ansible-pull

@@ -1,15 +1,5 @@
 #!/usr/bin/env python
 
-# ansible-pull is a script that runs ansible in local mode
-# after checking out a playbooks directory from git.  There is an
-# example playbook to bootstrap this script in the examples/ dir which
-# installs ansible and sets it up to run on cron.
-#
-# usage:
-#   ansible-pull -d /var/ansible/local -U http://wherever/content.git -C production
-#
-# the git repo must contain a playbook named 'local.yml'
-
 # (c) 2012, Stephen Fromm <sfromm@gmail.com>
 #
 # Ansible is free software: you can redistribute it and/or modify
@@ -24,47 +14,131 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# ansible-pull is a script that runs ansible in local mode
+# after checking out a playbooks directory from git.  There is an
+# example playbook to bootstrap this script in the examples/ dir which
+# installs ansible and sets it up to run on cron.
+
+# usage:
+#   ansible-pull -d /var/lib/ansible \
+#                -U http://example.net/content.git [-C production] \
+#                [path/playbook.yml]
+#
+# the -d and -U arguments are required; the -C argument is optional.
+#
+# ansible-pull accepts an optional argument to specify a playbook
+# location underneath the workdir and then searches the git repo
+# for playbooks in the following order, stopping at the first match:
+#
+# 1. $workdir/path/playbook.yml, if specified
+# 2. $workdir/$hostname.yml
+# 3. $workdir/local.yml
+#
+# the git repo must contain at least one of these playbooks.
 
 import os
+import shutil
 import subprocess
 import sys
+import datetime
+import socket
 from optparse import OptionParser
 
 DEFAULT_PLAYBOOK = 'local.yml'
+PLAYBOOK_ERRORS = { 1: 'File does not exist',
+                    2: 'File is not readable' }
 
 def _run(cmd):
+    print >>sys.stderr, "Running: '%s'" % cmd
     cmd = subprocess.Popen(cmd, shell=True,
                            stdout=subprocess.PIPE, stderr=subprocess.PIPE)
     (out, err) = cmd.communicate()
     print out
     if cmd.returncode != 0:
-        print err
+        print >>sys.stderr, err
     return cmd.returncode
 
+def try_playbook(path):
+    if not os.path.exists(path):
+        return 1
+    if not os.access(path, os.R_OK):
+        return 2
+    return 0
+
+def select_playbook(path, args):
+    playbook = None
+    if len(args) > 0 and args[0] is not None:
+        playbook = "%s/%s" % (path, args[0])
+        rc = try_playbook(playbook)
+        if rc != 0:
+            print >>sys.stderr, "%s: %s" % (playbook, PLAYBOOK_ERRORS[rc])
+            return None
+        return playbook
+    else:
+        hostpb = "%s/%s.yml" % (path, socket.getfqdn())
+        localpb = "%s/%s" % (path, DEFAULT_PLAYBOOK)
+        errors = []
+        for pb in [hostpb, localpb]:
+            rc = try_playbook(pb)
+            if rc == 0:
+                playbook = pb
+                break
+            else:
+                errors.append("%s: %s" % (pb, PLAYBOOK_ERRORS[rc]))
+        if playbook is None:
+            print >>sys.stderr, "\n".join(errors)
+        return playbook
+
 def main(args):
     """ Set up and run a local playbook """
-    usage = "%prog [options]"
-    parser = OptionParser()
+    usage = "%prog [options] [playbook.yml]"
+    parser = OptionParser(usage=usage)
+    parser.add_option('--purge', default=False, action='store_true',
+                      help='Purge git checkout after playbook run')
     parser.add_option('-d', '--directory', dest='dest', default=None,
-                      help='Directory to checkout git repository')
-    parser.add_option('-U', '--url', dest='url',
-                      default=None,
+                      help='Directory to clone git repository to')
+    parser.add_option('-U', '--url', dest='url', default=None,
                       help='URL of git repository')
     parser.add_option('-C', '--checkout', dest='checkout',
                       default="HEAD",
                       help='Branch/Tag/Commit to checkout.  Defaults to HEAD.')
     options, args = parser.parse_args(args)
 
+    if not options.dest:
+        parser.error("Missing required directory argument")
+        return 1
+
+    if not options.url:
+        parser.error("URL for git repo not specified, use -h for help")
+        return 1
+
+    now = datetime.datetime.now()
+    print >>sys.stderr, now.strftime("Starting ansible-pull at %F %T")
+
+    limit_opts = 'localhost:%s:127.0.0.1' % socket.getfqdn()
     git_opts = "repo=%s dest=%s version=%s" % (options.url, options.dest, options.checkout)
-    cmd = 'ansible all -c local -m git -a "%s"' % git_opts
-    print "cmd=%s" % cmd
+    cmd = 'ansible all -c local --limit "%s" -m git -a "%s"' % (limit_opts, git_opts)
     rc = _run(cmd)
     if rc != 0:
         return rc
 
+    playbook = select_playbook(options.dest, args)
+
+    if playbook is None:
+        print >>sys.stderr, "Could not find a playbook to run."
+        return 1
+
+    cmd = 'ansible-playbook -c local --limit "%s" %s' % (limit_opts, playbook)
     os.chdir(options.dest)
-    cmd = 'ansible-playbook -c local %s' % DEFAULT_PLAYBOOK
     rc = _run(cmd)
+
+    if options.purge:
+        os.chdir('/')
+        try:
+            shutil.rmtree(options.dest)
+        except Exception, e:
+            print >>sys.stderr, "Failed to remove %s: %s" % (options.dest, str(e))
+
     return rc
 
 if __name__ == '__main__':

docs/man/man1/ansible-doc.1

@@ -0,0 +1,57 @@
+'\" t
+.\"     Title: ansible-doc
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\"      Date: 02/01/2013
+.\"    Manual: System administration commands
+.\"    Source: Ansible 1.1
+.\"  Language: English
+.\"
+.TH "ANSIBLE\-DOC" "1" "02/01/2013" "Ansible 1\&.1" "System administration commands"
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+ansible-doc \- show documentation on Ansible modules
+.SH "SYNOPSIS"
+.sp
+ansible\-doc [\-M module_path] [\-l] [\-s] [module\&...]
+.SH "DESCRIPTION"
+.sp
+\fBansible\-doc\fR displays information on modules installed in Ansible libraries\&. It displays a terse listing of modules and their short descriptions, provides a printout of their DOCUMENTATION strings, and it can create a short "snippet" which can be pasted into a playbook\&.
+.SH "OPTIONS"
+.PP
+\fB\-M\fR \fIdirectory\fR, \fB\-\-module\-path=\fR\fIdirectory\fR
+.RS 4
+Add an additional directory to the default path for finding module libraries\&.
+.RE
+.PP
+\fB\-s\fR, \fB\-\-snippet=\fR
+.RS 4
+Produce a snippet which can be copied into a playbook for modification, like a kind of task template\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-list=\fR
+.RS 4
+Produce a terse listing of modules and a short description of each\&.
+.RE
+.SH "AUTHOR"
+.sp
+ansible\-doc was originally written by Jan\-Piet Mens\&. See the AUTHORS file for a complete list of contributors\&.
+.SH "COPYRIGHT"
+.sp
+Copyright \(co 2012, Jan\-Piet Mens
+.sp
+Ansible is released under the terms of the GPLv3 License\&.
+.SH "SEE ALSO"
+.sp
+\fBansible\-playbook\fR(1), \fBansible\fR(1)
+.sp
+Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/

docs/man/man1/ansible-doc.1.asciidoc.in

@@ -0,0 +1,65 @@
+ansible-doc(1)
+==============
+:doctype:manpage
+:man source:   Ansible
+:man version:  %VERSION%
+:man manual:   System administration commands
+
+NAME
+----
+ansible-doc - show documentation on Ansible modules
+
+
+SYNOPSIS
+--------
+ansible-doc [-M module_path] [-l] [-s] [module...]
+
+
+DESCRIPTION
+-----------
+
+*ansible-doc* displays information on modules installed in Ansible
+libraries. It displays a terse listing of modules and their short
+descriptions, provides a printout of their DOCUMENTATION strings,
+and it can create a short "snippet" which can be pasted into a
+playbook.
+
+
+OPTIONS
+-------
+
+*-M* 'directory', *--module-path=*'directory'::
+
+Add an additional directory to the default path for finding module libraries.
+
+*-s*, *--snippet=*::
+
+Produce a snippet which can be copied into a playbook for modification, like
+a kind of task template.
+
+*-l*, *--list=*::
+
+Produce a terse listing of modules and a short description of each.
+
+AUTHOR
+------
+
+ansible-doc was originally written by Jan-Piet Mens. See the AUTHORS file
+for a complete list of contributors.
+
+
+COPYRIGHT
+---------
+
+Copyright © 2012, Jan-Piet Mens
+
+Ansible is released under the terms of the GPLv3 License.
+
+
+SEE ALSO
+--------
+
+*ansible-playbook*(1), *ansible*(1), *ansible-pull*(1)
+
+Extensive documentation as well as IRC and mailing list info
+is available on the ansible home page: <https://ansible.github.com/>

docs/man/man1/ansible-playbook.1

@@ -2,12 +2,12 @@
 .\"     Title: ansible-playbook
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: 09/06/2012
+.\"      Date: 02/16/2013
 .\"    Manual: System administration commands
-.\"    Source: Ansible 0.7
+.\"    Source: Ansible 1.1
 .\"  Language: English
 .\"
-.TH "ANSIBLE\-PLAYBOOK" "1" "09/06/2012" "Ansible 0\&.7" "System administration commands"
+.TH "ANSIBLE\-PLAYBOOK" "1" "02/16/2013" "Ansible 1\&.1" "System administration commands"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------
@@ -82,6 +82,26 @@ Prompt for the password to use for playbook plays that request sudo access, if a
 Desired sudo user (default=root)\&.
 .RE
 .PP
+\fB\-\-tags\fR
+.RS 4
+Run only these tags from the playbook
+.RE
+.PP
+\fB\-\-syntax\-check\fR
+.RS 4
+Look for syntax errors in the playbook, but don\(cqt run anything
+.RE
+.PP
+\fB\-\-check\fR
+.RS 4
+Do not make any changes on the remote system, but test resources to see what might have changed\&. Note this can not scan all possible resource types and is only a simulation\&.
+.RE
+.PP
+\fB\-\-diff\fR
+.RS 4
+When changing any templated files, show the unified diffs of how they changed\&. When used with \-\-check, shows how the files would have changed if \-\-check were not used\&.
+.RE
+.PP
 \fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR
 .RS 4
 Connection timeout to use when trying to talk to hosts, in
@@ -120,6 +140,15 @@ The following environment variables may specified\&.
 ANSIBLE_HOSTS  \(em Override the default ansible hosts file
 .sp
 ANSIBLE_LIBRARY \(em Override the default ansible module library path
+.SH "FILES"
+.sp
+/etc/ansible/hosts \(em Default inventory file
+.sp
+/usr/share/ansible/ \(em Default module library
+.sp
+/etc/ansible/ansible\&.cfg \(em Config file, used if present
+.sp
+~/\&.ansible\&.cfg \(em User config file, overrides the default config if present
 .SH "AUTHOR"
 .sp
 Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.

docs/man/man1/ansible-playbook.1.asciidoc.in

@@ -73,6 +73,25 @@ access, if any.
 
 Desired sudo user (default=root).
 
+*--tags*::
+
+Run only these tags from the playbook
+
+*--syntax-check*::
+
+Look for syntax errors in the playbook, but don't run anything
+
+*--check*::
+
+Do not make any changes on the remote system, but test resources to see what might
+have changed.  Note this can not scan all possible resource types and is only
+a simulation.
+
+*--diff*::
+
+When changing any templated files, show the unified diffs of how they changed.  When
+used with --check, shows how the files would have changed if --check were not used.
+
 *-T* 'SECONDS', *--timeout=*'SECONDS'::
 
 Connection timeout to use when trying to talk to hosts, in 'SECONDS'.
@@ -107,6 +126,16 @@ ANSIBLE_HOSTS  -- Override the default ansible hosts file
 
 ANSIBLE_LIBRARY -- Override the default ansible module library path
 
+FILES
+-----
+
+/etc/ansible/hosts -- Default inventory file
+
+/usr/share/ansible/ -- Default module library
+
+/etc/ansible/ansible.cfg -- Config file, used if present
+
+~/.ansible.cfg -- User config file, overrides the default config if present
 
 AUTHOR
 ------
@@ -126,7 +155,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible*(1), *ansible-pull*(1)
+*ansible*(1), *ansible-pull*(1), *ansible-doc*(1)
 
 Extensive documentation as well as IRC and mailing list info
 is available on the ansible home page: <https://ansible.github.com/>

docs/man/man1/ansible-pull.1

@@ -1,22 +1,13 @@
 '\" t
 .\"     Title: ansible
 .\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 08/14/2012
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\"      Date: 02/01/2013
 .\"    Manual: System administration commands
-.\"    Source: Ansible 0.7
+.\"    Source: Ansible 1.1
 .\"  Language: English
 .\"
-.TH "ANSIBLE" "1" "08/14/2012" "Ansible 0\&.7" "System administration commands"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
+.TH "ANSIBLE" "1" "02/01/2013" "Ansible 1\&.1" "System administration commands"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------
@@ -34,7 +25,7 @@ ansible-pull \- set up a remote copy of ansible on each managed node
 ansible \-d DEST \-U URL [ \-C CHECKOUT ]
 .SH "DESCRIPTION"
 .sp
-\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq over SSH\&.
+\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&.
 .sp
 Use ansible\-pull to set up a remote copy of ansible on each managed node, each set to run via cron and update playbook source via git\&. This inverts the default \fBpush\fR architecture of ansible into a \fBpull\fR architecture, which has near\-limitless scaling potential\&.
 .sp

docs/man/man1/ansible-pull.1.asciidoc.in

@@ -70,7 +70,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible*(1), *ansible-playbook*(1)
+*ansible*(1), *ansible-playbook*(1), *ansible-doc*(1)
 
 Extensive documentation as well as IRC and mailing list info
 is available on the ansible home page: <https://ansible.github.com/>

docs/man/man1/ansible.1

@@ -2,12 +2,12 @@
 .\"     Title: ansible
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: 09/06/2012
+.\"      Date: 02/16/2013
 .\"    Manual: System administration commands
-.\"    Source: Ansible 0.7
+.\"    Source: Ansible 1.1
 .\"  Language: English
 .\"
-.TH "ANSIBLE" "1" "09/06/2012" "Ansible 0\&.7" "System administration commands"
+.TH "ANSIBLE" "1" "02/16/2013" "Ansible 1\&.1" "System administration commands"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------
@@ -131,7 +131,7 @@ seconds\&. Requires
 .RS 4
 Use this remote
 \fIUSERNAME\fR
-instead of root\&.
+instead of the current user\&.
 .RE
 .PP
 \fB\-U\fR \fISUDO_USERNAME\fR, \fB\-\-sudo\-user=\fR\fISUDO_USERNAME\fR
@@ -141,11 +141,6 @@ Sudo to
 instead of root\&. Implies \-\-sudo\&.
 .RE
 .PP
-\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
-.RS 4
-Use this file to authenticate the connection\&.
-.RE
-.PP
 \fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
 .RS 4
 Connection type to use\&. Possible options are
@@ -161,6 +156,11 @@ is mostly useful for crontab or kickstarts\&.
 .RS 4
 Further limits the selected host/group patterns\&.
 .RE
+.PP
+\fB\-l\fR \fI~REGEX\fR, \fB\-\-limit=\fR\fI~REGEX\fR
+.RS 4
+Further limits hosts with a regex pattern\&.
+.RE
 .SH "INVENTORY"
 .sp
 Ansible stores the hosts it can potentially operate on in an inventory file\&. The syntax is one host per line\&. Groups headers are allowed and are included on their own line, enclosed in square brackets that start the line\&.
@@ -171,6 +171,10 @@ Ranges of hosts are also supported\&. For more information and additional option
 /etc/ansible/hosts \(em Default inventory file
 .sp
 /usr/share/ansible/ \(em Default module library
+.sp
+/etc/ansible/ansible\&.cfg \(em Config file, used if present
+.sp
+~/\&.ansible\&.cfg \(em User config file, overrides the default config if present
 .SH "ENVIRONMENT"
 .sp
 The following environment variables may specified\&.
@@ -178,6 +182,8 @@ The following environment variables may specified\&.
 ANSIBLE_HOSTS  \(em Override the default ansible hosts file
 .sp
 ANSIBLE_LIBRARY \(em Override the default ansible module library path
+.sp
+ANSIBLE_CONFIG \(em Override the default ansible config file
 .SH "AUTHOR"
 .sp
 Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.

docs/man/man1/ansible.1.asciidoc.in

@@ -102,15 +102,12 @@ Poll a background job every 'NUM' seconds. Requires *-B*.
 
 *-u* 'USERNAME', *--remote-user=*'USERNAME'::
 
-Use this remote 'USERNAME' instead of root.
+Use this remote 'USERNAME' instead of the current user.
 
 *-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME'::
 
 Sudo to 'SUDO_USERNAME' instead of root.  Implies --sudo.
 
-*--private-key=*'PRIVATE_KEY_FILE'::
-Use this file to authenticate the connection.
-
 *-c* 'CONNECTION', *--connection=*'CONNECTION'::
 
 Connection type to use.  Possible options are 'paramiko' (SSH), 'ssh',
@@ -120,6 +117,10 @@ and 'local'.  'local' is mostly useful for crontab or kickstarts.
 
 Further limits the selected host/group patterns.
 
+*-l* '\~REGEX', *--limit=*'~REGEX'::
+
+Further limits hosts with a regex pattern.
+
 INVENTORY
 ---------
 
@@ -138,6 +139,9 @@ FILES
 
 /usr/share/ansible/ -- Default module library
 
+/etc/ansible/ansible.cfg -- Config file, used if present
+
+~/.ansible.cfg -- User config file, overrides the default config if present
 
 ENVIRONMENT
 -----------
@@ -148,6 +152,8 @@ ANSIBLE_HOSTS  -- Override the default ansible hosts file
 
 ANSIBLE_LIBRARY -- Override the default ansible module library path
 
+ANSIBLE_CONFIG -- Override the default ansible config file
+
 
 AUTHOR
 ------
@@ -167,7 +173,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible-playbook*(1), *ansible-pull*(1)
+*ansible-playbook*(1), *ansible-pull*(1), *ansible-doc*(1)
 
 Extensive documentation as well as IRC and mailing list info
 is available on the ansible home page: <https://ansible.github.com/>

docsite/.gitignore

@@ -0,0 +1,13 @@
+# Old compiled python stuff
+*.py[co]
+# package building stuff
+build
+# Emacs backup files...
+*~
+.\#*
+.doctrees
+# Generated docs stuff
+ansible*.xml
+.buildinfo
+objects.inv
+.doctrees

docsite/Makefile

@@ -0,0 +1,31 @@
+#!/usr/bin/make
+SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
+FORMATTER=../hacking/module_formatter.py
+
+all: clean docs
+
+docs: clean modules
+	./build-site.py
+
+viewdocs: clean
+	./build-site.py view
+
+htmldocs:
+	 ./build-site.py rst
+
+clean:
+	-rm -f .buildinfo
+	-rm -f *.inv
+	-rm -rf *.doctrees
+	@echo "Cleaning up byte compiled python stuff"
+	find . -regex ".*\.py[co]$$" -delete
+	@echo "Cleaning up editor backup files"
+	find . -type f \( -name "*~" -or -name "#*" \) -delete
+	find . -type f \( -name "*.swp" \) -delete
+
+.PHONEY: docs clean
+
+modules: $(FORMATTER) ../hacking/templates/rst.j2
+	PYTHONPATH=../lib $(FORMATTER) -t rst --template-dir=../hacking/templates --module-dir=../library -o rst/modules/ --includes-file=rst/modules/_list.rst
+
+

docsite/README.md

@@ -0,0 +1,23 @@
+Homepage and documentation source for the Ansible
+=================================================
+
+This project hosts the source behind [ansible.cc/docs](http://ansible.cc/docs)
+
+Contributions to the documentation are welcome.  To make changes, submit a pull request
+that changes the restructured text files in the "rst/" directory only, and Michael can
+do a docs build and push the static files.
+
+If you do not want to learn RST format (ReStructured Text), you can also file issues
+on the documentation project. 
+
+Note that module documentation can actually be generated from a DOCUMENTATION docstring
+in the modules directory, so corrections to modules written as much need to be made
+in the main project in the module source, rather than in the documentation for the module.
+
+Author
+======
+
+Michael DeHaan -- michael.dehaan@gmail.com
+
+[http://michaeldehaan.net](http://michaeldehaan.net/)
+

docsite/_static/ansible-local.css

@@ -0,0 +1,8 @@
+/* Local CSS tweaks for ansible */
+.dropdown-menu {
+    overflow-y: auto;
+}
+
+h2 {
+    padding-top: 40px;
+}

docsite/_static/basic.css

@@ -0,0 +1,540 @@
+/*
+ * basic.css
+ * ~~~~~~~~~
+ *
+ * Sphinx stylesheet -- basic theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+    clear: both;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+    width: 100%;
+    font-size: 90%;
+}
+
+div.related h3 {
+    display: none;
+}
+
+div.related ul {
+    margin: 0;
+    padding: 0 0 0 10px;
+    list-style: none;
+}
+
+div.related li {
+    display: inline;
+}
+
+div.related li.right {
+    float: right;
+    margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+    padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+    float: left;
+    width: 230px;
+    margin-left: -100%;
+    font-size: 90%;
+}
+
+div.sphinxsidebar ul {
+    list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+    margin-left: 20px;
+    list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+    margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox input[type="text"] {
+    width: 170px;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+    width: 30px;
+}
+
+img {
+    border: 0;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+    margin: 10px 0 0 20px;
+    padding: 0;
+}
+
+ul.search li {
+    padding: 5px 0 5px 20px;
+    background-image: url(file.png);
+    background-repeat: no-repeat;
+    background-position: 0 7px;
+}
+
+ul.search li a {
+    font-weight: bold;
+}
+
+ul.search li div.context {
+    color: #888;
+    margin: 2px 0 0 30px;
+    text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+    font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+    width: 90%;
+}
+
+table.contentstable p.biglink {
+    line-height: 150%;
+}
+
+a.biglink {
+    font-size: 1.3em;
+}
+
+span.linkdescr {
+    font-style: italic;
+    padding-top: 5px;
+    font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable {
+    width: 100%;
+}
+
+table.indextable td {
+    text-align: left;
+    vertical-align: top;
+}
+
+table.indextable dl, table.indextable dd {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+table.indextable tr.pcap {
+    height: 10px;
+}
+
+table.indextable tr.cap {
+    margin-top: 10px;
+    background-color: #f2f2f2;
+}
+
+img.toggler {
+    margin-right: 3px;
+    margin-top: 3px;
+    cursor: pointer;
+}
+
+div.modindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+a.headerlink {
+    visibility: hidden;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink {
+    visibility: visible;
+}
+
+div.body p.caption {
+    text-align: inherit;
+}
+
+div.body td {
+    text-align: left;
+}
+
+.field-list ul {
+    padding-left: 1em;
+}
+
+.first {
+    margin-top: 0 !important;
+}
+
+p.rubric {
+    margin-top: 30px;
+    font-weight: bold;
+}
+
+img.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+    text-align: left;
+}
+
+.align-center {
+    text-align: center;
+}
+
+.align-right {
+    text-align: right;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar {
+    margin: 0 0 0.5em 1em;
+    border: 1px solid #ddb;
+    padding: 7px 7px 0 7px;
+    background-color: #ffe;
+    width: 40%;
+    float: right;
+}
+
+p.sidebar-title {
+    font-weight: bold;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+div.topic {
+    border: 1px solid #ccc;
+    padding: 7px 7px 0 7px;
+    margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+    font-size: 1.1em;
+    font-weight: bold;
+    margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    padding: 7px;
+}
+
+div.admonition dt {
+    font-weight: bold;
+}
+
+div.admonition dl {
+    margin-bottom: 0;
+}
+
+p.admonition-title {
+    margin: 0px 10px 5px 0px;
+    font-weight: bold;
+}
+
+div.body p.centered {
+    text-align: center;
+    margin-top: 25px;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+    border: 0;
+    border-collapse: collapse;
+}
+
+table.docutils td, table.docutils th {
+    padding: 1px 8px 1px 5px;
+    border-top: 0;
+    border-left: 0;
+    border-right: 0;
+    border-bottom: 1px solid #aaa;
+}
+
+table.field-list td, table.field-list th {
+    border: 0 !important;
+}
+
+table.footnote td, table.footnote th {
+    border: 0 !important;
+}
+
+th {
+    text-align: left;
+    padding-right: 5px;
+}
+
+table.citation {
+    border-left: solid 1px gray;
+    margin-left: 1px;
+}
+
+table.citation td {
+    border-bottom: none;
+}
+
+/* -- other body styles ----------------------------------------------------- */
+
+ol.arabic {
+    list-style: decimal;
+}
+
+ol.loweralpha {
+    list-style: lower-alpha;
+}
+
+ol.upperalpha {
+    list-style: upper-alpha;
+}
+
+ol.lowerroman {
+    list-style: lower-roman;
+}
+
+ol.upperroman {
+    list-style: upper-roman;
+}
+
+dl {
+    margin-bottom: 15px;
+}
+
+dd p {
+    margin-top: 0px;
+}
+
+dd ul, dd table {
+    margin-bottom: 10px;
+}
+
+dd {
+    margin-top: 3px;
+    margin-bottom: 10px;
+    margin-left: 30px;
+}
+
+dt:target, .highlighted {
+    background-color: #fbe54e;
+}
+
+dl.glossary dt {
+    font-weight: bold;
+    font-size: 1.1em;
+}
+
+.field-list ul {
+    margin: 0;
+    padding-left: 1em;
+}
+
+.field-list p {
+    margin: 0;
+}
+
+.refcount {
+    color: #060;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.versionmodified {
+    font-style: italic;
+}
+
+.system-message {
+    background-color: #fda;
+    padding: 5px;
+    border: 3px solid red;
+}
+
+.footnote:target  {
+    background-color: #ffa;
+}
+
+.line-block {
+    display: block;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.line-block .line-block {
+    margin-top: 0;
+    margin-bottom: 0;
+    margin-left: 1.5em;
+}
+
+.guilabel, .menuselection {
+    font-family: sans-serif;
+}
+
+.accelerator {
+    text-decoration: underline;
+}
+
+.classifier {
+    font-style: oblique;
+}
+
+abbr, acronym {
+    border-bottom: dotted 1px;
+    cursor: help;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+    overflow: auto;
+    overflow-y: hidden;  /* fixes display issues on Chrome browsers */
+}
+
+td.linenos pre {
+    padding: 5px 0px;
+    border: 0;
+    background-color: transparent;
+    color: #aaa;
+}
+
+table.highlighttable {
+    margin-left: 0.5em;
+}
+
+table.highlighttable td {
+    padding: 0 0.5em 0 0.5em;
+}
+
+tt.descname {
+    background-color: transparent;
+    font-weight: bold;
+    font-size: 1.2em;
+}
+
+tt.descclassname {
+    background-color: transparent;
+}
+
+tt.xref, a tt {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+    background-color: transparent;
+}
+
+.viewcode-link {
+    float: right;
+}
+
+.viewcode-back {
+    float: right;
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    margin: -1px -10px;
+    padding: 0 10px;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+    vertical-align: middle;
+}
+
+div.body div.math p {
+    text-align: center;
+}
+
+span.eqno {
+    float: right;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+    div.document,
+    div.documentwrapper,
+    div.bodywrapper {
+        margin: 0 !important;
+        width: 100%;
+    }
+
+    div.sphinxsidebar,
+    div.related,
+    div.footer,
+    #top-link {
+        display: none;
+    }
+}

docsite/_static/bootstrap-dropdown.js

@@ -0,0 +1,55 @@
+/* ============================================================
+ * bootstrap-dropdown.js v1.4.0
+ * http://twitter.github.com/bootstrap/javascript.html#dropdown
+ * ============================================================
+ * Copyright 2011 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============================================================ */
+
+
+!function( $ ){
+
+  "use strict"
+
+  /* DROPDOWN PLUGIN DEFINITION
+   * ========================== */
+
+  $.fn.dropdown = function ( selector ) {
+    return this.each(function () {
+      $(this).delegate(selector || d, 'click', function (e) {
+        var li = $(this).parent('li')
+          , isActive = li.hasClass('open')
+
+        clearMenus()
+        !isActive && li.toggleClass('open')
+        return false
+      })
+    })
+  }
+
+  /* APPLY TO STANDARD DROPDOWN ELEMENTS
+   * =================================== */
+
+  var d = 'a.menu, .dropdown-toggle'
+
+  function clearMenus() {
+    $(d).parent('li').removeClass('open')
+  }
+
+  $(function () {
+    $('html').bind("click", clearMenus)
+    $('body').dropdown( '[data-dropdown] a.menu, [data-dropdown] .dropdown-toggle' )
+  })
+
+}( window.jQuery || window.ender );

docsite/_static/bootstrap-scrollspy.js

@@ -0,0 +1,107 @@
+/* =============================================================
+ * bootstrap-scrollspy.js v1.4.0
+ * http://twitter.github.com/bootstrap/javascript.html#scrollspy
+ * =============================================================
+ * Copyright 2011 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============================================================== */
+
+
+!function ( $ ) {
+
+  "use strict"
+
+  var $window = $(window)
+
+  function ScrollSpy( topbar, selector ) {
+    var processScroll = $.proxy(this.processScroll, this)
+    this.$topbar = $(topbar)
+    this.selector = selector || 'li > a'
+    this.refresh()
+    this.$topbar.delegate(this.selector, 'click', processScroll)
+    $window.scroll(processScroll)
+    this.processScroll()
+  }
+
+  ScrollSpy.prototype = {
+
+      refresh: function () {
+        this.targets = this.$topbar.find(this.selector).map(function () {
+          var href = $(this).attr('href')
+          return /^#\w/.test(href) && $(href).length ? href : null
+        })
+
+        this.offsets = $.map(this.targets, function (id) {
+          return $(id).offset().top
+        })
+      }
+
+    , processScroll: function () {
+        var scrollTop = $window.scrollTop() + 10
+          , offsets = this.offsets
+          , targets = this.targets
+          , activeTarget = this.activeTarget
+          , i
+
+        for (i = offsets.length; i--;) {
+          activeTarget != targets[i]
+            && scrollTop >= offsets[i]
+            && (!offsets[i + 1] || scrollTop <= offsets[i + 1])
+            && this.activateButton( targets[i] )
+        }
+      }
+
+    , activateButton: function (target) {
+        this.activeTarget = target
+
+        this.$topbar
+          .find(this.selector).parent('.active')
+          .removeClass('active')
+
+        this.$topbar
+          .find(this.selector + '[href="' + target + '"]')
+          .parent('li')
+          .addClass('active')
+      }
+
+  }
+
+  /* SCROLLSPY PLUGIN DEFINITION
+   * =========================== */
+
+  $.fn.scrollSpy = function( options ) {
+    var scrollspy = this.data('scrollspy')
+
+    if (!scrollspy) {
+      return this.each(function () {
+        $(this).data('scrollspy', new ScrollSpy( this, options ))
+      })
+    }
+
+    if ( options === true ) {
+      return scrollspy
+    }
+
+    if ( typeof options == 'string' ) {
+      scrollspy[options]()
+    }
+
+    return this
+  }
+
+  $(document).ready(function () {
+    $('body').scrollSpy('[data-scrollspy] li > a')
+  })
+
+}( window.jQuery || window.ender );

docsite/_static/bootstrap-sphinx.css

@@ -0,0 +1,15 @@
+/*
+* bootstrap-sphinx.css
+* ~~~~~~~~~~~~~~~~~~~~
+*
+* Sphinx stylesheet -- Twitter Bootstrap theme.
+*/
+
+body {
+  padding-top: 42px;
+}
+
+div.documentwrapper {
+  float: left;
+  width: 100%;
+}

docsite/_static/default.css

@@ -0,0 +1,256 @@
+/*
+ * default.css_t
+ * ~~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- default theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+    font-family: sans-serif;
+    font-size: 100%;
+    background-color: #11303d;
+    color: #000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    background-color: #1c4e63;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 230px;
+}
+
+div.body {
+    background-color: #ffffff;
+    color: #000000;
+    padding: 0 20px 30px 20px;
+}
+
+div.footer {
+    color: #ffffff;
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.footer a {
+    color: #ffffff;
+    text-decoration: underline;
+}
+
+div.related {
+    background-color: #133f52;
+    line-height: 30px;
+    color: #ffffff;
+}
+
+div.related a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar {
+}
+
+div.sphinxsidebar h3 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.4em;
+    font-weight: normal;
+    margin: 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h3 a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar h4 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.3em;
+    font-weight: normal;
+    margin: 5px 0 0 0;
+    padding: 0;
+}
+
+div.sphinxsidebar p {
+    color: #ffffff;
+}
+
+div.sphinxsidebar p.topless {
+    margin: 5px 10px 10px 10px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px;
+    padding: 0;
+    color: #ffffff;
+}
+
+div.sphinxsidebar a {
+    color: #98dbcc;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+
+
+/* -- hyperlink styles ------------------------------------------------------ */
+
+a {
+    color: #355f7c;
+    text-decoration: none;
+}
+
+a:visited {
+    color: #355f7c;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+
+
+/* -- body styles ----------------------------------------------------------- */
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: 'Trebuchet MS', sans-serif;
+    background-color: #f2f2f2;
+    font-weight: normal;
+    color: #20435c;
+    border-bottom: 1px solid #ccc;
+    margin: 20px -20px 10px -20px;
+    padding: 3px 0 3px 10px;
+}
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 160%; }
+div.body h3 { font-size: 140%; }
+div.body h4 { font-size: 120%; }
+div.body h5 { font-size: 110%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: #c60f0f;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: #c60f0f;
+    color: white;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: justify;
+    line-height: 130%;
+}
+
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.admonition p {
+    margin-bottom: 5px;
+}
+
+div.admonition pre {
+    margin-bottom: 5px;
+}
+
+div.admonition ul, div.admonition ol {
+    margin-bottom: 5px;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+
+p.admonition-title {
+    display: inline;
+}
+
+p.admonition-title:after {
+    content: ":";
+}
+
+pre {
+    padding: 5px;
+    background-color: #eeffcc;
+    color: #333333;
+    line-height: 120%;
+    border: 1px solid #ac9;
+    border-left: none;
+    border-right: none;
+}
+
+tt {
+    background-color: #ecf0f3;
+    padding: 0 1px 0 1px;
+    font-size: 0.95em;
+}
+
+th {
+    background-color: #ede;
+}
+
+.warning tt {
+    background: #efc2c2;
+}
+
+.note tt {
+    background: #d6d6d6;
+}
+
+.viewcode-back {
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}

docsite/_static/doctools.js

@@ -0,0 +1,247 @@
+/*
+ * doctools.js
+ * ~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilities for all documentation.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/**
+ * select a different prefix for underscore
+ */
+$u = _.noConflict();
+
+/**
+ * make the code below compatible with browsers without
+ * an installed firebug like debugger
+if (!window.console || !console.firebug) {
+  var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
+    "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
+    "profile", "profileEnd"];
+  window.console = {};
+  for (var i = 0; i < names.length; ++i)
+    window.console[names[i]] = function() {};
+}
+ */
+
+/**
+ * small helper function to urldecode strings
+ */
+jQuery.urldecode = function(x) {
+  return decodeURIComponent(x).replace(/\+/g, ' ');
+}
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+  if (typeof s == 'undefined')
+    s = document.location.search;
+  var parts = s.substr(s.indexOf('?') + 1).split('&');
+  var result = {};
+  for (var i = 0; i < parts.length; i++) {
+    var tmp = parts[i].split('=', 2);
+    var key = jQuery.urldecode(tmp[0]);
+    var value = jQuery.urldecode(tmp[1]);
+    if (key in result)
+      result[key].push(value);
+    else
+      result[key] = [value];
+  }
+  return result;
+};
+
+/**
+ * small function to check if an array contains
+ * a given item.
+ */
+jQuery.contains = function(arr, item) {
+  for (var i = 0; i < arr.length; i++) {
+    if (arr[i] == item)
+      return true;
+  }
+  return false;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+  function highlight(node) {
+    if (node.nodeType == 3) {
+      var val = node.nodeValue;
+      var pos = val.toLowerCase().indexOf(text);
+      if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) {
+        var span = document.createElement("span");
+        span.className = className;
+        span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+        node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+          document.createTextNode(val.substr(pos + text.length)),
+          node.nextSibling));
+        node.nodeValue = val.substr(0, pos);
+      }
+    }
+    else if (!jQuery(node).is("button, select, textarea")) {
+      jQuery.each(node.childNodes, function() {
+        highlight(this);
+      });
+    }
+  }
+  return this.each(function() {
+    highlight(this);
+  });
+};
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+var Documentation = {
+
+  init : function() {
+    this.fixFirefoxAnchorBug();
+    this.highlightSearchWords();
+    this.initIndexTable();
+  },
+
+  /**
+   * i18n support
+   */
+  TRANSLATIONS : {},
+  PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; },
+  LOCALE : 'unknown',
+
+  // gettext and ngettext don't access this so that the functions
+  // can safely bound to a different name (_ = Documentation.gettext)
+  gettext : function(string) {
+    var translated = Documentation.TRANSLATIONS[string];
+    if (typeof translated == 'undefined')
+      return string;
+    return (typeof translated == 'string') ? translated : translated[0];
+  },
+
+  ngettext : function(singular, plural, n) {
+    var translated = Documentation.TRANSLATIONS[singular];
+    if (typeof translated == 'undefined')
+      return (n == 1) ? singular : plural;
+    return translated[Documentation.PLURALEXPR(n)];
+  },
+
+  addTranslations : function(catalog) {
+    for (var key in catalog.messages)
+      this.TRANSLATIONS[key] = catalog.messages[key];
+    this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
+    this.LOCALE = catalog.locale;
+  },
+
+  /**
+   * add context elements like header anchor links
+   */
+  addContextElements : function() {
+    $('div[id] > :header:first').each(function() {
+      $('<a class="headerlink">\u00B6</a>').
+      attr('href', '#' + this.id).
+      attr('title', _('Permalink to this headline')).
+      appendTo(this);
+    });
+    $('dt[id]').each(function() {
+      $('<a class="headerlink">\u00B6</a>').
+      attr('href', '#' + this.id).
+      attr('title', _('Permalink to this definition')).
+      appendTo(this);
+    });
+  },
+
+  /**
+   * workaround a firefox stupidity
+   */
+  fixFirefoxAnchorBug : function() {
+    if (document.location.hash && $.browser.mozilla)
+      window.setTimeout(function() {
+        document.location.href += '';
+      }, 10);
+  },
+
+  /**
+   * highlight the search words provided in the url in the text
+   */
+  highlightSearchWords : function() {
+    var params = $.getQueryParameters();
+    var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
+    if (terms.length) {
+      var body = $('div.body');
+      window.setTimeout(function() {
+        $.each(terms, function() {
+          body.highlightText(this.toLowerCase(), 'highlighted');
+        });
+      }, 10);
+      $('<p class="highlight-link"><a href="javascript:Documentation.' +
+        'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
+          .appendTo($('#searchbox'));
+    }
+  },
+
+  /**
+   * init the domain index toggle buttons
+   */
+  initIndexTable : function() {
+    var togglers = $('img.toggler').click(function() {
+      var src = $(this).attr('src');
+      var idnum = $(this).attr('id').substr(7);
+      $('tr.cg-' + idnum).toggle();
+      if (src.substr(-9) == 'minus.png')
+        $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
+      else
+        $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
+    }).css('display', '');
+    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
+        togglers.click();
+    }
+  },
+
+  /**
+   * helper function to hide the search marks again
+   */
+  hideSearchWords : function() {
+    $('#searchbox .highlight-link').fadeOut(300);
+    $('span.highlighted').removeClass('highlighted');
+  },
+
+  /**
+   * make the url absolute
+   */
+  makeURL : function(relativeURL) {
+    return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
+  },
+
+  /**
+   * get the current relative url
+   */
+  getCurrentURL : function() {
+    var path = document.location.pathname;
+    var parts = path.split(/\//);
+    $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
+      if (this == '..')
+        parts.pop();
+    });
+    var url = parts.join('/');
+    return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
+  }
+};
+
+// quick alias for translations
+_ = Documentation.gettext;
+
+$(document).ready(function() {
+  Documentation.init();
+});

docsite/_static/jquery.js

@@ -0,0 +1,154 @@
+/*!
+ * jQuery JavaScript Library v1.4.2
+ * http://jquery.com/
+ *
+ * Copyright 2010, John Resig
+ * Dual licensed under the MIT or GPL Version 2 licenses.
+ * http://jquery.org/license
+ *
+ * Includes Sizzle.js
+ * http://sizzlejs.com/
+ * Copyright 2010, The Dojo Foundation
+ * Released under the MIT, BSD, and GPL Licenses.
+ *
+ * Date: Sat Feb 13 22:33:48 2010 -0500
+ */
+(function(A,w){function ma(){if(!c.isReady){try{s.documentElement.doScroll("left")}catch(a){setTimeout(ma,1);return}c.ready()}}function Qa(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,j){var i=a.length;if(typeof b==="object"){for(var o in b)X(a,o,b[o],f,e,d);return a}if(d!==w){f=!j&&f&&c.isFunction(d);for(o=0;o<i;o++)e(a[o],b,f?d.call(a[o],o,e(a[o],b)):d,j);return a}return i?
+e(a[0],b):w}function J(){return(new Date).getTime()}function Y(){return false}function Z(){return true}function na(a,b,d){d[0].type=a;return c.event.handle.apply(b,d)}function oa(a){var b,d=[],f=[],e=arguments,j,i,o,k,n,r;i=c.data(this,"events");if(!(a.liveFired===this||!i||!i.live||a.button&&a.type==="click")){a.liveFired=this;var u=i.live.slice(0);for(k=0;k<u.length;k++){i=u[k];i.origType.replace(O,"")===a.type?f.push(i.selector):u.splice(k--,1)}j=c(a.target).closest(f,a.currentTarget);n=0;for(r=
+j.length;n<r;n++)for(k=0;k<u.length;k++){i=u[k];if(j[n].selector===i.selector){o=j[n].elem;f=null;if(i.preType==="mouseenter"||i.preType==="mouseleave")f=c(a.relatedTarget).closest(i.selector)[0];if(!f||f!==o)d.push({elem:o,handleObj:i})}}n=0;for(r=d.length;n<r;n++){j=d[n];a.currentTarget=j.elem;a.data=j.handleObj.data;a.handleObj=j.handleObj;if(j.handleObj.origHandler.apply(j.elem,e)===false){b=false;break}}return b}}function pa(a,b){return"live."+(a&&a!=="*"?a+".":"")+b.replace(/\./g,"`").replace(/ /g,
+"&")}function qa(a){return!a||!a.parentNode||a.parentNode.nodeType===11}function ra(a,b){var d=0;b.each(function(){if(this.nodeName===(a[d]&&a[d].nodeName)){var f=c.data(a[d++]),e=c.data(this,f);if(f=f&&f.events){delete e.handle;e.events={};for(var j in f)for(var i in f[j])c.event.add(this,j,f[j][i],f[j][i].data)}}})}function sa(a,b,d){var f,e,j;b=b&&b[0]?b[0].ownerDocument||b[0]:s;if(a.length===1&&typeof a[0]==="string"&&a[0].length<512&&b===s&&!ta.test(a[0])&&(c.support.checkClone||!ua.test(a[0]))){e=
+true;if(j=c.fragments[a[0]])if(j!==1)f=j}if(!f){f=b.createDocumentFragment();c.clean(a,b,f,d)}if(e)c.fragments[a[0]]=j?f:1;return{fragment:f,cacheable:e}}function K(a,b){var d={};c.each(va.concat.apply([],va.slice(0,b)),function(){d[this]=a});return d}function wa(a){return"scrollTo"in a&&a.document?a:a.nodeType===9?a.defaultView||a.parentWindow:false}var c=function(a,b){return new c.fn.init(a,b)},Ra=A.jQuery,Sa=A.$,s=A.document,T,Ta=/^[^<]*(<[\w\W]+>)[^>]*$|^#([\w-]+)$/,Ua=/^.[^:#\[\.,]*$/,Va=/\S/,
+Wa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Xa=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,P=navigator.userAgent,xa=false,Q=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,R=Array.prototype.slice,ya=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(a==="body"&&!b){this.context=s;this[0]=s.body;this.selector="body";this.length=1;return this}if(typeof a==="string")if((d=Ta.exec(a))&&
+(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:s;if(a=Xa.exec(a))if(c.isPlainObject(b)){a=[s.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=sa([d[1]],[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}return c.merge(this,a)}else{if(b=s.getElementById(d[2])){if(b.id!==d[2])return T.find(a);this.length=1;this[0]=b}this.context=s;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=s;a=s.getElementsByTagName(a);return c.merge(this,
+a)}else return!b||b.jquery?(b||T).find(a):c(b).find(a);else if(c.isFunction(a))return T.ready(a);if(a.selector!==w){this.selector=a.selector;this.context=a.context}return c.makeArray(a,this)},selector:"",jquery:"1.4.2",length:0,size:function(){return this.length},toArray:function(){return R.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){var f=c();c.isArray(a)?ba.apply(f,a):c.merge(f,a);f.prevObject=this;f.context=this.context;if(b===
+"find")f.selector=this.selector+(this.selector?" ":"")+d;else if(b)f.selector=this.selector+"."+b+"("+d+")";return f},each:function(a,b){return c.each(this,a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(s,c);else Q&&Q.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(R.apply(this,arguments),"slice",R.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this,
+function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice};c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,j,i,o;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b<d;b++)if((e=arguments[b])!=null)for(j in e){i=a[j];o=e[j];if(a!==o)if(f&&o&&(c.isPlainObject(o)||c.isArray(o))){i=i&&(c.isPlainObject(i)||
+c.isArray(i))?i:c.isArray(o)?[]:{};a[j]=c.extend(f,i,o)}else if(o!==w)a[j]=o}return a};c.extend({noConflict:function(a){A.$=Sa;if(a)A.jQuery=Ra;return c},isReady:false,ready:function(){if(!c.isReady){if(!s.body)return setTimeout(c.ready,13);c.isReady=true;if(Q){for(var a,b=0;a=Q[b++];)a.call(s,c);Q=null}c.fn.triggerHandler&&c(s).triggerHandler("ready")}},bindReady:function(){if(!xa){xa=true;if(s.readyState==="complete")return c.ready();if(s.addEventListener){s.addEventListener("DOMContentLoaded",
+L,false);A.addEventListener("load",c.ready,false)}else if(s.attachEvent){s.attachEvent("onreadystatechange",L);A.attachEvent("onload",c.ready);var a=false;try{a=A.frameElement==null}catch(b){}s.documentElement.doScroll&&a&&ma()}}},isFunction:function(a){return $.call(a)==="[object Function]"},isArray:function(a){return $.call(a)==="[object Array]"},isPlainObject:function(a){if(!a||$.call(a)!=="[object Object]"||a.nodeType||a.setInterval)return false;if(a.constructor&&!aa.call(a,"constructor")&&!aa.call(a.constructor.prototype,
+"isPrototypeOf"))return false;var b;for(b in a);return b===w||aa.call(a,b)},isEmptyObject:function(a){for(var b in a)return false;return true},error:function(a){throw a;},parseJSON:function(a){if(typeof a!=="string"||!a)return null;a=c.trim(a);if(/^[\],:{}\s]*$/.test(a.replace(/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,"@").replace(/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,"]").replace(/(?:^|:|,)(?:\s*\[)+/g,"")))return A.JSON&&A.JSON.parse?A.JSON.parse(a):(new Function("return "+
+a))();else c.error("Invalid JSON: "+a)},noop:function(){},globalEval:function(a){if(a&&Va.test(a)){var b=s.getElementsByTagName("head")[0]||s.documentElement,d=s.createElement("script");d.type="text/javascript";if(c.support.scriptEval)d.appendChild(s.createTextNode(a));else d.text=a;b.insertBefore(d,b.firstChild);b.removeChild(d)}},nodeName:function(a,b){return a.nodeName&&a.nodeName.toUpperCase()===b.toUpperCase()},each:function(a,b,d){var f,e=0,j=a.length,i=j===w||c.isFunction(a);if(d)if(i)for(f in a){if(b.apply(a[f],
+d)===false)break}else for(;e<j;){if(b.apply(a[e++],d)===false)break}else if(i)for(f in a){if(b.call(a[f],f,a[f])===false)break}else for(d=a[0];e<j&&b.call(d,e,d)!==false;d=a[++e]);return a},trim:function(a){return(a||"").replace(Wa,"")},makeArray:function(a,b){b=b||[];if(a!=null)a.length==null||typeof a==="string"||c.isFunction(a)||typeof a!=="function"&&a.setInterval?ba.call(b,a):c.merge(b,a);return b},inArray:function(a,b){if(b.indexOf)return b.indexOf(a);for(var d=0,f=b.length;d<f;d++)if(b[d]===
+a)return d;return-1},merge:function(a,b){var d=a.length,f=0;if(typeof b.length==="number")for(var e=b.length;f<e;f++)a[d++]=b[f];else for(;b[f]!==w;)a[d++]=b[f++];a.length=d;return a},grep:function(a,b,d){for(var f=[],e=0,j=a.length;e<j;e++)!d!==!b(a[e],e)&&f.push(a[e]);return f},map:function(a,b,d){for(var f=[],e,j=0,i=a.length;j<i;j++){e=b(a[j],j,d);if(e!=null)f[f.length]=e}return f.concat.apply([],f)},guid:1,proxy:function(a,b,d){if(arguments.length===2)if(typeof b==="string"){d=a;a=d[b];b=w}else if(b&&
+!c.isFunction(b)){d=b;b=w}if(!b&&a)b=function(){return a.apply(d||this,arguments)};if(a)b.guid=a.guid=a.guid||b.guid||c.guid++;return b},uaMatch:function(a){a=a.toLowerCase();a=/(webkit)[ \/]([\w.]+)/.exec(a)||/(opera)(?:.*version)?[ \/]([\w.]+)/.exec(a)||/(msie) ([\w.]+)/.exec(a)||!/compatible/.test(a)&&/(mozilla)(?:.*? rv:([\w.]+))?/.exec(a)||[];return{browser:a[1]||"",version:a[2]||"0"}},browser:{}});P=c.uaMatch(P);if(P.browser){c.browser[P.browser]=true;c.browser.version=P.version}if(c.browser.webkit)c.browser.safari=
+true;if(ya)c.inArray=function(a,b){return ya.call(b,a)};T=c(s);if(s.addEventListener)L=function(){s.removeEventListener("DOMContentLoaded",L,false);c.ready()};else if(s.attachEvent)L=function(){if(s.readyState==="complete"){s.detachEvent("onreadystatechange",L);c.ready()}};(function(){c.support={};var a=s.documentElement,b=s.createElement("script"),d=s.createElement("div"),f="script"+J();d.style.display="none";d.innerHTML="   <link/><table></table><a href='/a' style='color:red;float:left;opacity:.55;'>a</a><input type='checkbox'/>";
+var e=d.getElementsByTagName("*"),j=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!j)){c.support={leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(j.getAttribute("style")),hrefNormalized:j.getAttribute("href")==="/a",opacity:/^0.55$/.test(j.style.opacity),cssFloat:!!j.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:s.createElement("select").appendChild(s.createElement("option")).selected,
+parentNode:d.removeChild(d.appendChild(s.createElement("div"))).parentNode===null,deleteExpando:true,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null};b.type="text/javascript";try{b.appendChild(s.createTextNode("window."+f+"=1;"))}catch(i){}a.insertBefore(b,a.firstChild);if(A[f]){c.support.scriptEval=true;delete A[f]}try{delete b.test}catch(o){c.support.deleteExpando=false}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function k(){c.support.noCloneEvent=
+false;d.detachEvent("onclick",k)});d.cloneNode(true).fireEvent("onclick")}d=s.createElement("div");d.innerHTML="<input type='radio' name='radiotest' checked='checked'/>";a=s.createDocumentFragment();a.appendChild(d.firstChild);c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var k=s.createElement("div");k.style.width=k.style.paddingLeft="1px";s.body.appendChild(k);c.boxModel=c.support.boxModel=k.offsetWidth===2;s.body.removeChild(k).style.display="none"});a=function(k){var n=
+s.createElement("div");k="on"+k;var r=k in n;if(!r){n.setAttribute(k,"return;");r=typeof n[k]==="function"}return r};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=j=null}})();c.props={"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ya=0,za={};c.extend({cache:{},expando:G,noData:{embed:true,object:true,
+applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var f=a[G],e=c.cache;if(!f&&typeof b==="string"&&d===w)return null;f||(f=++Ya);if(typeof b==="object"){a[G]=f;e[f]=c.extend(true,{},b)}else if(!e[f]){a[G]=f;e[f]={}}a=e[f];if(d!==w)a[b]=d;return typeof b==="string"?a[b]:a}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{if(c.support.deleteExpando)delete a[c.expando];
+else a.removeAttribute&&a.removeAttribute(c.expando);delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this,a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===w){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===w&&this.length)f=c.data(this[0],a);return f===w&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this,
+a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d);return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b===
+w)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]||a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var Aa=/[\n\t]/g,ca=/\s+/,Za=/\r/g,$a=/href|src|style/,ab=/(button|input)/i,bb=/(button|input|object|select|textarea)/i,
+cb=/^(a|area)$/i,Ba=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(n){var r=c(this);r.addClass(a.call(this,n,r.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1)if(e.className){for(var j=" "+e.className+" ",
+i=e.className,o=0,k=b.length;o<k;o++)if(j.indexOf(" "+b[o]+" ")<0)i+=" "+b[o];e.className=c.trim(i)}else e.className=a}return this},removeClass:function(a){if(c.isFunction(a))return this.each(function(k){var n=c(this);n.removeClass(a.call(this,k,n.attr("class")))});if(a&&typeof a==="string"||a===w)for(var b=(a||"").split(ca),d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1&&e.className)if(a){for(var j=(" "+e.className+" ").replace(Aa," "),i=0,o=b.length;i<o;i++)j=j.replace(" "+b[i]+" ",
+" ");e.className=c.trim(j)}else e.className=""}return this},toggleClass:function(a,b){var d=typeof a,f=typeof b==="boolean";if(c.isFunction(a))return this.each(function(e){var j=c(this);j.toggleClass(a.call(this,e,j.attr("class"),b),b)});return this.each(function(){if(d==="string")for(var e,j=0,i=c(this),o=b,k=a.split(ca);e=k[j++];){o=f?o:!i.hasClass(e);i[o?"addClass":"removeClass"](e)}else if(d==="undefined"||d==="boolean"){this.className&&c.data(this,"__className__",this.className);this.className=
+this.className||a===false?"":c.data(this,"__className__")||""}})},hasClass:function(a){a=" "+a+" ";for(var b=0,d=this.length;b<d;b++)if((" "+this[b].className+" ").replace(Aa," ").indexOf(a)>-1)return true;return false},val:function(a){if(a===w){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value||{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var j=b?d:0;for(d=b?d+1:e.length;j<d;j++){var i=
+e[j];if(i.selected){a=c(i).val();if(b)return a;f.push(a)}}return f}if(Ba.test(b.type)&&!c.support.checkOn)return b.getAttribute("value")===null?"on":b.value;return(b.value||"").replace(Za,"")}return w}var o=c.isFunction(a);return this.each(function(k){var n=c(this),r=a;if(this.nodeType===1){if(o)r=a.call(this,k,n.val());if(typeof r==="number")r+="";if(c.isArray(r)&&Ba.test(this.type))this.checked=c.inArray(n.val(),r)>=0;else if(c.nodeName(this,"select")){var u=c.makeArray(r);c("option",this).each(function(){this.selected=
+c.inArray(c(this).val(),u)>=0});if(!u.length)this.selectedIndex=-1}else this.value=r}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return w;if(f&&b in c.attrFn)return c(a)[b](d);f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==w;b=f&&c.props[b]||b;if(a.nodeType===1){var j=$a.test(b);if(b in a&&f&&!j){if(e){b==="type"&&ab.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed");
+a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:bb.test(a.nodeName)||cb.test(a.nodeName)&&a.href?0:w;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText=""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&j?a.getAttribute(b,2):a.getAttribute(b);return a===null?w:a}return c.style(a,b,d)}});var O=/\.(.*)$/,db=function(a){return a.replace(/[^\w\s\.\|`]/g,
+function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==A&&!a.frameElement)a=A;var e,j;if(d.handler){e=d;d=e.handler}if(!d.guid)d.guid=c.guid++;if(j=c.data(a)){var i=j.events=j.events||{},o=j.handle;if(!o)j.handle=o=function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(o.elem,arguments):w};o.elem=a;b=b.split(" ");for(var k,n=0,r;k=b[n++];){j=e?c.extend({},e):{handler:d,data:f};if(k.indexOf(".")>-1){r=k.split(".");
+k=r.shift();j.namespace=r.slice(0).sort().join(".")}else{r=[];j.namespace=""}j.type=k;j.guid=d.guid;var u=i[k],z=c.event.special[k]||{};if(!u){u=i[k]=[];if(!z.setup||z.setup.call(a,f,r,o)===false)if(a.addEventListener)a.addEventListener(k,o,false);else a.attachEvent&&a.attachEvent("on"+k,o)}if(z.add){z.add.call(a,j);if(!j.handler.guid)j.handler.guid=d.guid}u.push(j);c.event.global[k]=true}a=null}}},global:{},remove:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){var e,j=0,i,o,k,n,r,u,z=c.data(a),
+C=z&&z.events;if(z&&C){if(b&&b.type){d=b.handler;b=b.type}if(!b||typeof b==="string"&&b.charAt(0)==="."){b=b||"";for(e in C)c.event.remove(a,e+b)}else{for(b=b.split(" ");e=b[j++];){n=e;i=e.indexOf(".")<0;o=[];if(!i){o=e.split(".");e=o.shift();k=new RegExp("(^|\\.)"+c.map(o.slice(0).sort(),db).join("\\.(?:.*\\.)?")+"(\\.|$)")}if(r=C[e])if(d){n=c.event.special[e]||{};for(B=f||0;B<r.length;B++){u=r[B];if(d.guid===u.guid){if(i||k.test(u.namespace)){f==null&&r.splice(B--,1);n.remove&&n.remove.call(a,u)}if(f!=
+null)break}}if(r.length===0||f!=null&&r.length===1){if(!n.teardown||n.teardown.call(a,o)===false)Ca(a,e,z.handle);delete C[e]}}else for(var B=0;B<r.length;B++){u=r[B];if(i||k.test(u.namespace)){c.event.remove(a,n,u.handler,B);r.splice(B--,1)}}}if(c.isEmptyObject(C)){if(b=z.handle)b.elem=null;delete z.events;delete z.handle;c.isEmptyObject(z)&&c.removeData(a)}}}}},trigger:function(a,b,d,f){var e=a.type||a;if(!f){a=typeof a==="object"?a[G]?a:c.extend(c.Event(e),a):c.Event(e);if(e.indexOf("!")>=0){a.type=
+e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();c.event.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return w;a.result=w;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d,b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(j){}if(!a.isPropagationStopped()&&
+f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){f=a.target;var i,o=c.nodeName(f,"a")&&e==="click",k=c.event.special[e]||{};if((!k._default||k._default.call(d,a)===false)&&!o&&!(f&&f.nodeName&&c.noData[f.nodeName.toLowerCase()])){try{if(f[e]){if(i=f["on"+e])f["on"+e]=null;c.event.triggered=true;f[e]()}}catch(n){}if(i)f["on"+e]=i;c.event.triggered=false}}},handle:function(a){var b,d,f,e;a=arguments[0]=c.event.fix(a||A.event);a.currentTarget=this;b=a.type.indexOf(".")<0&&!a.exclusive;
+if(!b){d=a.type.split(".");a.type=d.shift();f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)")}e=c.data(this,"events");d=e[a.type];if(e&&d){d=d.slice(0);e=0;for(var j=d.length;e<j;e++){var i=d[e];if(b||f.test(i.namespace)){a.handler=i.handler;a.data=i.data;a.handleObj=i;i=i.handler.apply(this,arguments);if(i!==w){a.result=i;if(i===false){a.preventDefault();a.stopPropagation()}}if(a.isImmediatePropagationStopped())break}}}return a.result},props:"altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode layerX layerY metaKey newValue offsetX offsetY originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target toElement view wheelDelta which".split(" "),
+fix:function(a){if(a[G])return a;var b=a;a=c.Event(b);for(var d=this.props.length,f;d;){f=this.props[--d];a[f]=b[f]}if(!a.target)a.target=a.srcElement||s;if(a.target.nodeType===3)a.target=a.target.parentNode;if(!a.relatedTarget&&a.fromElement)a.relatedTarget=a.fromElement===a.target?a.toElement:a.fromElement;if(a.pageX==null&&a.clientX!=null){b=s.documentElement;d=s.body;a.pageX=a.clientX+(b&&b.scrollLeft||d&&d.scrollLeft||0)-(b&&b.clientLeft||d&&d.clientLeft||0);a.pageY=a.clientY+(b&&b.scrollTop||
+d&&d.scrollTop||0)-(b&&b.clientTop||d&&d.clientTop||0)}if(!a.which&&(a.charCode||a.charCode===0?a.charCode:a.keyCode))a.which=a.charCode||a.keyCode;if(!a.metaKey&&a.ctrlKey)a.metaKey=a.ctrlKey;if(!a.which&&a.button!==w)a.which=a.button&1?1:a.button&2?3:a.button&4?2:0;return a},guid:1E8,proxy:c.proxy,special:{ready:{setup:c.bindReady,teardown:c.noop},live:{add:function(a){c.event.add(this,a.origType,c.extend({},a,{handler:oa}))},remove:function(a){var b=true,d=a.origType.replace(O,"");c.each(c.data(this,
+"events").live||[],function(){if(d===this.origType.replace(O,""))return b=false});b&&c.event.remove(this,a.origType,oa)}},beforeunload:{setup:function(a,b,d){if(this.setInterval)this.onbeforeunload=d;return false},teardown:function(a,b){if(this.onbeforeunload===b)this.onbeforeunload=null}}}};var Ca=s.removeEventListener?function(a,b,d){a.removeEventListener(b,d,false)}:function(a,b,d){a.detachEvent("on"+b,d)};c.Event=function(a){if(!this.preventDefault)return new c.Event(a);if(a&&a.type){this.originalEvent=
+a;this.type=a.type}else this.type=a;this.timeStamp=J();this[G]=true};c.Event.prototype={preventDefault:function(){this.isDefaultPrevented=Z;var a=this.originalEvent;if(a){a.preventDefault&&a.preventDefault();a.returnValue=false}},stopPropagation:function(){this.isPropagationStopped=Z;var a=this.originalEvent;if(a){a.stopPropagation&&a.stopPropagation();a.cancelBubble=true}},stopImmediatePropagation:function(){this.isImmediatePropagationStopped=Z;this.stopPropagation()},isDefaultPrevented:Y,isPropagationStopped:Y,
+isImmediatePropagationStopped:Y};var Da=function(a){var b=a.relatedTarget;try{for(;b&&b!==this;)b=b.parentNode;if(b!==this){a.type=a.data;c.event.handle.apply(this,arguments)}}catch(d){}},Ea=function(a){a.type=a.data;c.event.handle.apply(this,arguments)};c.each({mouseenter:"mouseover",mouseleave:"mouseout"},function(a,b){c.event.special[a]={setup:function(d){c.event.add(this,b,d&&d.selector?Ea:Da,a)},teardown:function(d){c.event.remove(this,b,d&&d.selector?Ea:Da)}}});if(!c.support.submitBubbles)c.event.special.submit=
+{setup:function(){if(this.nodeName.toLowerCase()!=="form"){c.event.add(this,"click.specialSubmit",function(a){var b=a.target,d=b.type;if((d==="submit"||d==="image")&&c(b).closest("form").length)return na("submit",this,arguments)});c.event.add(this,"keypress.specialSubmit",function(a){var b=a.target,d=b.type;if((d==="text"||d==="password")&&c(b).closest("form").length&&a.keyCode===13)return na("submit",this,arguments)})}else return false},teardown:function(){c.event.remove(this,".specialSubmit")}};
+if(!c.support.changeBubbles){var da=/textarea|input|select/i,ea,Fa=function(a){var b=a.type,d=a.value;if(b==="radio"||b==="checkbox")d=a.checked;else if(b==="select-multiple")d=a.selectedIndex>-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d},fa=function(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Fa(d);if(a.type!=="focusout"||d.type!=="radio")c.data(d,"_change_data",
+e);if(!(f===w||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}};c.event.special.change={filters:{focusout:fa,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return fa.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return fa.call(this,a)},beforeactivate:function(a){a=a.target;c.data(a,
+"_change_data",Fa(a))}},setup:function(){if(this.type==="file")return false;for(var a in ea)c.event.add(this,a+".specialChange",ea[a]);return da.test(this.nodeName)},teardown:function(){c.event.remove(this,".specialChange");return da.test(this.nodeName)}};ea=c.event.special.change.filters}s.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this,f)}c.event.special[b]={setup:function(){this.addEventListener(a,
+d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var j in d)this[b](j,f,d[j],e);return this}if(c.isFunction(f)){e=f;f=w}var i=b==="one"?c.proxy(e,function(k){c(this).unbind(k,i);return e.apply(this,arguments)}):e;if(d==="unload"&&b!=="one")this.one(d,f,e);else{j=0;for(var o=this.length;j<o;j++)c.event.add(this[j],d,i,f)}return this}});c.fn.extend({unbind:function(a,b){if(typeof a==="object"&&
+!a.preventDefault)for(var d in a)this.unbind(d,a[d]);else{d=0;for(var f=this.length;d<f;d++)c.event.remove(this[d],a,b)}return this},delegate:function(a,b,d,f){return this.live(b,d,f,a)},undelegate:function(a,b,d){return arguments.length===0?this.unbind("live"):this.die(b,null,d,a)},trigger:function(a,b){return this.each(function(){c.event.trigger(a,b,this)})},triggerHandler:function(a,b){if(this[0]){a=c.Event(a);a.preventDefault();a.stopPropagation();c.event.trigger(a,b,this[0]);return a.result}},
+toggle:function(a){for(var b=arguments,d=1;d<b.length;)c.proxy(a,b[d++]);return this.click(c.proxy(a,function(f){var e=(c.data(this,"lastToggle"+a.guid)||0)%d;c.data(this,"lastToggle"+a.guid,e+1);f.preventDefault();return b[e].apply(this,arguments)||false}))},hover:function(a,b){return this.mouseenter(a).mouseleave(b||a)}});var Ga={focus:"focusin",blur:"focusout",mouseenter:"mouseover",mouseleave:"mouseout"};c.each(["live","die"],function(a,b){c.fn[b]=function(d,f,e,j){var i,o=0,k,n,r=j||this.selector,
+u=j?this:c(this.context);if(c.isFunction(f)){e=f;f=w}for(d=(d||"").split(" ");(i=d[o++])!=null;){j=O.exec(i);k="";if(j){k=j[0];i=i.replace(O,"")}if(i==="hover")d.push("mouseenter"+k,"mouseleave"+k);else{n=i;if(i==="focus"||i==="blur"){d.push(Ga[i]+k);i+=k}else i=(Ga[i]||i)+k;b==="live"?u.each(function(){c.event.add(this,pa(i,r),{data:f,selector:r,handler:e,origType:i,origHandler:e,preType:n})}):u.unbind(pa(i,r),e)}}return this}});c.each("blur focus focusin focusout load resize scroll unload click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup error".split(" "),
+function(a,b){c.fn[b]=function(d){return d?this.bind(b,d):this.trigger(b)};if(c.attrFn)c.attrFn[b]=true});A.attachEvent&&!A.addEventListener&&A.attachEvent("onunload",function(){for(var a in c.cache)if(c.cache[a].handle)try{c.event.remove(c.cache[a].handle.elem)}catch(b){}});(function(){function a(g){for(var h="",l,m=0;g[m];m++){l=g[m];if(l.nodeType===3||l.nodeType===4)h+=l.nodeValue;else if(l.nodeType!==8)h+=a(l.childNodes)}return h}function b(g,h,l,m,q,p){q=0;for(var v=m.length;q<v;q++){var t=m[q];
+if(t){t=t[g];for(var y=false;t;){if(t.sizcache===l){y=m[t.sizset];break}if(t.nodeType===1&&!p){t.sizcache=l;t.sizset=q}if(t.nodeName.toLowerCase()===h){y=t;break}t=t[g]}m[q]=y}}}function d(g,h,l,m,q,p){q=0;for(var v=m.length;q<v;q++){var t=m[q];if(t){t=t[g];for(var y=false;t;){if(t.sizcache===l){y=m[t.sizset];break}if(t.nodeType===1){if(!p){t.sizcache=l;t.sizset=q}if(typeof h!=="string"){if(t===h){y=true;break}}else if(k.filter(h,[t]).length>0){y=t;break}}t=t[g]}m[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,
+e=0,j=Object.prototype.toString,i=false,o=true;[0,0].sort(function(){o=false;return 0});var k=function(g,h,l,m){l=l||[];var q=h=h||s;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g||typeof g!=="string")return l;for(var p=[],v,t,y,S,H=true,M=x(h),I=g;(f.exec(""),v=f.exec(I))!==null;){I=v[3];p.push(v[1]);if(v[2]){S=v[3];break}}if(p.length>1&&r.exec(g))if(p.length===2&&n.relative[p[0]])t=ga(p[0]+p[1],h);else for(t=n.relative[p[0]]?[h]:k(p.shift(),h);p.length;){g=p.shift();if(n.relative[g])g+=p.shift();
+t=ga(g,t)}else{if(!m&&p.length>1&&h.nodeType===9&&!M&&n.match.ID.test(p[0])&&!n.match.ID.test(p[p.length-1])){v=k.find(p.shift(),h,M);h=v.expr?k.filter(v.expr,v.set)[0]:v.set[0]}if(h){v=m?{expr:p.pop(),set:z(m)}:k.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=v.expr?k.filter(v.expr,v.set):v.set;if(p.length>0)y=z(t);else H=false;for(;p.length;){var D=p.pop();v=D;if(n.relative[D])v=p.pop();else D="";if(v==null)v=h;n.relative[D](y,v,M)}}else y=[]}y||(y=t);y||k.error(D||
+g);if(j.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))l.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&&y[g].nodeType===1&&l.push(t[g]);else l.push.apply(l,y);else z(y,l);if(S){k(S,q,l,m);k.uniqueSort(l)}return l};k.uniqueSort=function(g){if(B){i=o;g.sort(B);if(i)for(var h=1;h<g.length;h++)g[h]===g[h-1]&&g.splice(h--,1)}return g};k.matches=function(g,h){return k(g,null,null,h)};k.find=function(g,h,l){var m,q;if(!g)return[];
+for(var p=0,v=n.order.length;p<v;p++){var t=n.order[p];if(q=n.leftMatch[t].exec(g)){var y=q[1];q.splice(1,1);if(y.substr(y.length-1)!=="\\"){q[1]=(q[1]||"").replace(/\\/g,"");m=n.find[t](q,h,l);if(m!=null){g=g.replace(n.match[t],"");break}}}}m||(m=h.getElementsByTagName("*"));return{set:m,expr:g}};k.filter=function(g,h,l,m){for(var q=g,p=[],v=h,t,y,S=h&&h[0]&&x(h[0]);g&&h.length;){for(var H in n.filter)if((t=n.leftMatch[H].exec(g))!=null&&t[2]){var M=n.filter[H],I,D;D=t[1];y=false;t.splice(1,1);if(D.substr(D.length-
+1)!=="\\"){if(v===p)p=[];if(n.preFilter[H])if(t=n.preFilter[H](t,v,l,p,m,S)){if(t===true)continue}else y=I=true;if(t)for(var U=0;(D=v[U])!=null;U++)if(D){I=M(D,t,U,v);var Ha=m^!!I;if(l&&I!=null)if(Ha)y=true;else v[U]=false;else if(Ha){p.push(D);y=true}}if(I!==w){l||(v=p);g=g.replace(n.match[H],"");if(!y)return[];break}}}if(g===q)if(y==null)k.error(g);else break;q=g}return v};k.error=function(g){throw"Syntax error, unrecognized expression: "+g;};var n=k.selectors={order:["ID","NAME","TAG"],match:{ID:/#((?:[\w\u00c0-\uFFFF-]|\\.)+)/,
+CLASS:/\.((?:[\w\u00c0-\uFFFF-]|\\.)+)/,NAME:/\[name=['"]*((?:[\w\u00c0-\uFFFF-]|\\.)+)['"]*\]/,ATTR:/\[\s*((?:[\w\u00c0-\uFFFF-]|\\.)+)\s*(?:(\S?=)\s*(['"]*)(.*?)\3|)\s*\]/,TAG:/^((?:[\w\u00c0-\uFFFF\*-]|\\.)+)/,CHILD:/:(only|nth|last|first)-child(?:\((even|odd|[\dn+-]*)\))?/,POS:/:(nth|eq|gt|lt|first|last|even|odd)(?:\((\d*)\))?(?=[^-]|$)/,PSEUDO:/:((?:[\w\u00c0-\uFFFF-]|\\.)+)(?:\((['"]?)((?:\([^\)]+\)|[^\(\)]*)+)\2\))?/},leftMatch:{},attrMap:{"class":"className","for":"htmlFor"},attrHandle:{href:function(g){return g.getAttribute("href")}},
+relative:{"+":function(g,h){var l=typeof h==="string",m=l&&!/\W/.test(h);l=l&&!m;if(m)h=h.toLowerCase();m=0;for(var q=g.length,p;m<q;m++)if(p=g[m]){for(;(p=p.previousSibling)&&p.nodeType!==1;);g[m]=l||p&&p.nodeName.toLowerCase()===h?p||false:p===h}l&&k.filter(h,g,true)},">":function(g,h){var l=typeof h==="string";if(l&&!/\W/.test(h)){h=h.toLowerCase();for(var m=0,q=g.length;m<q;m++){var p=g[m];if(p){l=p.parentNode;g[m]=l.nodeName.toLowerCase()===h?l:false}}}else{m=0;for(q=g.length;m<q;m++)if(p=g[m])g[m]=
+l?p.parentNode:p.parentNode===h;l&&k.filter(h,g,true)}},"":function(g,h,l){var m=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p=h=h.toLowerCase();q=b}q("parentNode",h,m,g,p,l)},"~":function(g,h,l){var m=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p=h=h.toLowerCase();q=b}q("previousSibling",h,m,g,p,l)}},find:{ID:function(g,h,l){if(typeof h.getElementById!=="undefined"&&!l)return(g=h.getElementById(g[1]))?[g]:[]},NAME:function(g,h){if(typeof h.getElementsByName!=="undefined"){var l=[];
+h=h.getElementsByName(g[1]);for(var m=0,q=h.length;m<q;m++)h[m].getAttribute("name")===g[1]&&l.push(h[m]);return l.length===0?null:l}},TAG:function(g,h){return h.getElementsByTagName(g[1])}},preFilter:{CLASS:function(g,h,l,m,q,p){g=" "+g[1].replace(/\\/g,"")+" ";if(p)return g;p=0;for(var v;(v=h[p])!=null;p++)if(v)if(q^(v.className&&(" "+v.className+" ").replace(/[\t\n]/g," ").indexOf(g)>=0))l||m.push(v);else if(l)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()},
+CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&&"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,l,m,q,p){h=g[1].replace(/\\/g,"");if(!p&&n.attrMap[h])g[1]=n.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,l,m,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=k(g[3],null,null,h);else{g=k.filter(g[3],h,l,true^q);l||m.push.apply(m,
+g);return false}else if(n.match.POS.test(g[0])||n.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true);return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,l){return!!k(l[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)},
+text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"===g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}},
+setFilters:{first:function(g,h){return h===0},last:function(g,h,l,m){return h===m.length-1},even:function(g,h){return h%2===0},odd:function(g,h){return h%2===1},lt:function(g,h,l){return h<l[3]-0},gt:function(g,h,l){return h>l[3]-0},nth:function(g,h,l){return l[3]-0===h},eq:function(g,h,l){return l[3]-0===h}},filter:{PSEUDO:function(g,h,l,m){var q=h[1],p=n.filters[q];if(p)return p(g,l,h,m);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h=
+h[3];l=0;for(m=h.length;l<m;l++)if(h[l]===g)return false;return true}else k.error("Syntax error, unrecognized expression: "+q)},CHILD:function(g,h){var l=h[1],m=g;switch(l){case "only":case "first":for(;m=m.previousSibling;)if(m.nodeType===1)return false;if(l==="first")return true;m=g;case "last":for(;m=m.nextSibling;)if(m.nodeType===1)return false;return true;case "nth":l=h[2];var q=h[3];if(l===1&&q===0)return true;h=h[0];var p=g.parentNode;if(p&&(p.sizcache!==h||!g.nodeIndex)){var v=0;for(m=p.firstChild;m;m=
+m.nextSibling)if(m.nodeType===1)m.nodeIndex=++v;p.sizcache=h}g=g.nodeIndex-q;return l===0?g===0:g%l===0&&g/l>=0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var l=h[1];g=n.attrHandle[l]?n.attrHandle[l](g):g[l]!=null?g[l]:g.getAttribute(l);l=g+"";var m=h[2];h=h[4];return g==null?m==="!=":m===
+"="?l===h:m==="*="?l.indexOf(h)>=0:m==="~="?(" "+l+" ").indexOf(h)>=0:!h?l&&g!==false:m==="!="?l!==h:m==="^="?l.indexOf(h)===0:m==="$="?l.substr(l.length-h.length)===h:m==="|="?l===h||l.substr(0,h.length+1)===h+"-":false},POS:function(g,h,l,m){var q=n.setFilters[h[2]];if(q)return q(g,l,h,m)}}},r=n.match.POS;for(var u in n.match){n.match[u]=new RegExp(n.match[u].source+/(?![^\[]*\])(?![^\(]*\))/.source);n.leftMatch[u]=new RegExp(/(^(?:.|\r|\n)*?)/.source+n.match[u].source.replace(/\\(\d+)/g,function(g,
+h){return"\\"+(h-0+1)}))}var z=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g};try{Array.prototype.slice.call(s.documentElement.childNodes,0)}catch(C){z=function(g,h){h=h||[];if(j.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var l=0,m=g.length;l<m;l++)h.push(g[l]);else for(l=0;g[l];l++)h.push(g[l]);return h}}var B;if(s.documentElement.compareDocumentPosition)B=function(g,h){if(!g.compareDocumentPosition||
+!h.compareDocumentPosition){if(g==h)i=true;return g.compareDocumentPosition?-1:1}g=g.compareDocumentPosition(h)&4?-1:g===h?0:1;if(g===0)i=true;return g};else if("sourceIndex"in s.documentElement)B=function(g,h){if(!g.sourceIndex||!h.sourceIndex){if(g==h)i=true;return g.sourceIndex?-1:1}g=g.sourceIndex-h.sourceIndex;if(g===0)i=true;return g};else if(s.createRange)B=function(g,h){if(!g.ownerDocument||!h.ownerDocument){if(g==h)i=true;return g.ownerDocument?-1:1}var l=g.ownerDocument.createRange(),m=
+h.ownerDocument.createRange();l.setStart(g,0);l.setEnd(g,0);m.setStart(h,0);m.setEnd(h,0);g=l.compareBoundaryPoints(Range.START_TO_END,m);if(g===0)i=true;return g};(function(){var g=s.createElement("div"),h="script"+(new Date).getTime();g.innerHTML="<a name='"+h+"'/>";var l=s.documentElement;l.insertBefore(g,l.firstChild);if(s.getElementById(h)){n.find.ID=function(m,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(m[1]))?q.id===m[1]||typeof q.getAttributeNode!=="undefined"&&
+q.getAttributeNode("id").nodeValue===m[1]?[q]:w:[]};n.filter.ID=function(m,q){var p=typeof m.getAttributeNode!=="undefined"&&m.getAttributeNode("id");return m.nodeType===1&&p&&p.nodeValue===q}}l.removeChild(g);l=g=null})();(function(){var g=s.createElement("div");g.appendChild(s.createComment(""));if(g.getElementsByTagName("*").length>0)n.find.TAG=function(h,l){l=l.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var m=0;l[m];m++)l[m].nodeType===1&&h.push(l[m]);l=h}return l};g.innerHTML="<a href='#'></a>";
+if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")n.attrHandle.href=function(h){return h.getAttribute("href",2)};g=null})();s.querySelectorAll&&function(){var g=k,h=s.createElement("div");h.innerHTML="<p class='TEST'></p>";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){k=function(m,q,p,v){q=q||s;if(!v&&q.nodeType===9&&!x(q))try{return z(q.querySelectorAll(m),p)}catch(t){}return g(m,q,p,v)};for(var l in g)k[l]=g[l];h=null}}();
+(function(){var g=s.createElement("div");g.innerHTML="<div class='test e'></div><div class='test'></div>";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length===0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){n.order.splice(1,0,"CLASS");n.find.CLASS=function(h,l,m){if(typeof l.getElementsByClassName!=="undefined"&&!m)return l.getElementsByClassName(h[1])};g=null}}})();var E=s.compareDocumentPosition?function(g,h){return!!(g.compareDocumentPosition(h)&16)}:
+function(g,h){return g!==h&&(g.contains?g.contains(h):true)},x=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},ga=function(g,h){var l=[],m="",q;for(h=h.nodeType?[h]:h;q=n.match.PSEUDO.exec(g);){m+=q[0];g=g.replace(n.match.PSEUDO,"")}g=n.relative[g]?g+"*":g;q=0;for(var p=h.length;q<p;q++)k(g,h[q],l);return k.filter(m,l)};c.find=k;c.expr=k.selectors;c.expr[":"]=c.expr.filters;c.unique=k.uniqueSort;c.text=a;c.isXMLDoc=x;c.contains=E})();var eb=/Until$/,fb=/^(?:parents|prevUntil|prevAll)/,
+gb=/,/;R=Array.prototype.slice;var Ia=function(a,b,d){if(c.isFunction(b))return c.grep(a,function(e,j){return!!b.call(e,j,e)===d});else if(b.nodeType)return c.grep(a,function(e){return e===b===d});else if(typeof b==="string"){var f=c.grep(a,function(e){return e.nodeType===1});if(Ua.test(b))return c.filter(b,f,!d);else b=c.filter(b,f)}return c.grep(a,function(e){return c.inArray(e,b)>=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f<e;f++){d=b.length;
+c.find(a,this[f],b);if(f>0)for(var j=d;j<b.length;j++)for(var i=0;i<d;i++)if(b[i]===b[j]){b.splice(j--,1);break}}return b},has:function(a){var b=c(a);return this.filter(function(){for(var d=0,f=b.length;d<f;d++)if(c.contains(this,b[d]))return true})},not:function(a){return this.pushStack(Ia(this,a,false),"not",a)},filter:function(a){return this.pushStack(Ia(this,a,true),"filter",a)},is:function(a){return!!a&&c.filter(a,this).length>0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,j=
+{},i;if(f&&a.length){e=0;for(var o=a.length;e<o;e++){i=a[e];j[i]||(j[i]=c.expr.match.POS.test(i)?c(i,b||this.context):i)}for(;f&&f.ownerDocument&&f!==b;){for(i in j){e=j[i];if(e.jquery?e.index(f)>-1:c(f).is(e)){d.push({selector:i,elem:f});delete j[i]}}f=f.parentNode}}return d}var k=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(n,r){for(;r&&r.ownerDocument&&r!==b;){if(k?k.index(r)>-1:c(r).is(a))return r;r=r.parentNode}return null})},index:function(a){if(!a||typeof a===
+"string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(),a);return this.pushStack(qa(a[0])||qa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode",
+d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")},nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")?
+a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);eb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e):e;if((this.length>1||gb.test(f))&&fb.test(a))e=e.reverse();return this.pushStack(e,a,R.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===w||a.nodeType!==1||!c(a).is(d));){a.nodeType===
+1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!==b&&d.push(a);return d}});var Ja=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ka=/(<([\w:]+)[^>]*?)\/>/g,hb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,La=/<([\w:]+)/,ib=/<tbody/i,jb=/<|&#?\w+;/,ta=/<script|<object|<embed|<option|<style/i,ua=/checked\s*(?:[^=]|=\s*.checked.)/i,Ma=function(a,b,d){return hb.test(d)?
+a:b+"></"+d+">"},F={option:[1,"<select multiple='multiple'>","</select>"],legend:[1,"<fieldset>","</fieldset>"],thead:[1,"<table>","</table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"],col:[2,"<table><tbody></tbody><colgroup>","</colgroup></table>"],area:[1,"<map>","</map>"],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div<div>","</div>"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d=
+c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==w)return this.empty().append((this[0]&&this[0].ownerDocument||s).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this},
+wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})},
+prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,
+this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,f;(f=this[d])!=null;d++)if(!a||c.filter(a,[f]).length){if(!b&&f.nodeType===1){c.cleanData(f.getElementsByTagName("*"));c.cleanData([f])}f.parentNode&&f.parentNode.removeChild(f)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild);
+return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Ja,"").replace(/=([^="'>\s]+\/)>/g,'="$1">').replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){ra(this,b);ra(this.find("*"),b.find("*"))}return b},html:function(a){if(a===w)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Ja,
+""):null;else if(typeof a==="string"&&!ta.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(La.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Ka,Ma);try{for(var b=0,d=this.length;b<d;b++)if(this[b].nodeType===1){c.cleanData(this[b].getElementsByTagName("*"));this[b].innerHTML=a}}catch(f){this.empty().append(a)}}else c.isFunction(a)?this.each(function(e){var j=c(this),i=j.html();j.empty().append(function(){return a.call(this,e,i)})}):this.empty().append(a);return this},replaceWith:function(a){if(this[0]&&
+this[0].parentNode){if(c.isFunction(a))return this.each(function(b){var d=c(this),f=d.html();d.replaceWith(a.call(this,b,f))});if(typeof a!=="string")a=c(a).detach();return this.each(function(){var b=this.nextSibling,d=this.parentNode;c(this).remove();b?c(b).before(a):c(d).append(a)})}else return this.pushStack(c(c.isFunction(a)?a():a),"replaceWith",a)},detach:function(a){return this.remove(a,true)},domManip:function(a,b,d){function f(u){return c.nodeName(u,"table")?u.getElementsByTagName("tbody")[0]||
+u.appendChild(u.ownerDocument.createElement("tbody")):u}var e,j,i=a[0],o=[],k;if(!c.support.checkClone&&arguments.length===3&&typeof i==="string"&&ua.test(i))return this.each(function(){c(this).domManip(a,b,d,true)});if(c.isFunction(i))return this.each(function(u){var z=c(this);a[0]=i.call(this,u,b?z.html():w);z.domManip(a,b,d)});if(this[0]){e=i&&i.parentNode;e=c.support.parentNode&&e&&e.nodeType===11&&e.childNodes.length===this.length?{fragment:e}:sa(a,this,o);k=e.fragment;if(j=k.childNodes.length===
+1?(k=k.firstChild):k.firstChild){b=b&&c.nodeName(j,"tr");for(var n=0,r=this.length;n<r;n++)d.call(b?f(this[n],j):this[n],n>0||e.cacheable||this.length>1?k.cloneNode(true):k)}o.length&&c.each(o,Qa)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);var e=this.length===1&&this[0].parentNode;if(e&&e.nodeType===11&&e.childNodes.length===1&&d.length===1){d[b](this[0]);
+return this}else{e=0;for(var j=d.length;e<j;e++){var i=(e>0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),i);f=f.concat(i)}return this.pushStack(f,a,d.selector)}}});c.extend({clean:function(a,b,d,f){b=b||s;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||s;for(var e=[],j=0,i;(i=a[j])!=null;j++){if(typeof i==="number")i+="";if(i){if(typeof i==="string"&&!jb.test(i))i=b.createTextNode(i);else if(typeof i==="string"){i=i.replace(Ka,Ma);var o=(La.exec(i)||["",
+""])[1].toLowerCase(),k=F[o]||F._default,n=k[0],r=b.createElement("div");for(r.innerHTML=k[1]+i+k[2];n--;)r=r.lastChild;if(!c.support.tbody){n=ib.test(i);o=o==="table"&&!n?r.firstChild&&r.firstChild.childNodes:k[1]==="<table>"&&!n?r.childNodes:[];for(k=o.length-1;k>=0;--k)c.nodeName(o[k],"tbody")&&!o[k].childNodes.length&&o[k].parentNode.removeChild(o[k])}!c.support.leadingWhitespace&&V.test(i)&&r.insertBefore(b.createTextNode(V.exec(i)[0]),r.firstChild);i=r.childNodes}if(i.nodeType)e.push(i);else e=
+c.merge(e,i)}}if(d)for(j=0;e[j];j++)if(f&&c.nodeName(e[j],"script")&&(!e[j].type||e[j].type.toLowerCase()==="text/javascript"))f.push(e[j].parentNode?e[j].parentNode.removeChild(e[j]):e[j]);else{e[j].nodeType===1&&e.splice.apply(e,[j+1,0].concat(c.makeArray(e[j].getElementsByTagName("script"))));d.appendChild(e[j])}return e},cleanData:function(a){for(var b,d,f=c.cache,e=c.event.special,j=c.support.deleteExpando,i=0,o;(o=a[i])!=null;i++)if(d=o[c.expando]){b=f[d];if(b.events)for(var k in b.events)e[k]?
+c.event.remove(o,k):Ca(o,k,b.handle);if(j)delete o[c.expando];else o.removeAttribute&&o.removeAttribute(c.expando);delete f[d]}}});var kb=/z-?index|font-?weight|opacity|zoom|line-?height/i,Na=/alpha\([^)]*\)/,Oa=/opacity=([^)]*)/,ha=/float/i,ia=/-([a-z])/ig,lb=/([A-Z])/g,mb=/^-?\d+(?:px)?$/i,nb=/^-?\d/,ob={position:"absolute",visibility:"hidden",display:"block"},pb=["Left","Right"],qb=["Top","Bottom"],rb=s.defaultView&&s.defaultView.getComputedStyle,Pa=c.support.cssFloat?"cssFloat":"styleFloat",ja=
+function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===w)return c.curCSS(d,f);if(typeof e==="number"&&!kb.test(f))e+="px";c.style(d,f,e)})};c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return w;if((b==="width"||b==="height")&&parseFloat(d)<0)d=w;var f=a.style||a,e=d!==w;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter=
+Na.test(a)?a.replace(Na,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Oa.exec(f.filter)[1])/100+"":""}if(ha.test(b))b=Pa;b=b.replace(ia,ja);if(e)f[b]=d;return f[b]},css:function(a,b,d,f){if(b==="width"||b==="height"){var e,j=b==="width"?pb:qb;function i(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(j,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a,
+"border"+this+"Width",true))||0})}a.offsetWidth!==0?i():c.swap(a,ob,i);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&&a.currentStyle){f=Oa.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ha.test(b))b=Pa;if(!d&&e&&e[b])f=e[b];else if(rb){if(ha.test(b))b="float";b=b.replace(lb,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f=
+a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ia,ja);f=a.currentStyle[b]||a.currentStyle[d];if(!mb.test(f)&&nb.test(f)){b=e.left;var j=a.runtimeStyle.left;a.runtimeStyle.left=a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=j}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b=
+a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var sb=J(),tb=/<script(.|\s)*?\/script>/gi,ub=/select|textarea/i,vb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ka=/\?/,wb=/(\?|&)_=.*?(&|$)/,xb=/^(\w+:)?\/\/([^\/?#]+)/,yb=/%20/g,zb=c.fn.load;c.fn.extend({load:function(a,b,d){if(typeof a!==
+"string")return zb.call(this,a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b=c.param(b,c.ajaxSettings.traditional);f="POST"}var j=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(i,o){if(o==="success"||o==="notmodified")j.html(e?c("<div />").append(i.responseText.replace(tb,"")).find(e):i.responseText);d&&j.each(d,[i.responseText,o,i])}});return this},
+serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||ub.test(this.nodeName)||vb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),
+function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a,b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href,
+global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:A.XMLHttpRequest&&(A.location.protocol!=="file:"||!A.ActiveXObject)?function(){return new A.XMLHttpRequest}:function(){try{return new A.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&&
+e.success.call(k,o,i,x);e.global&&f("ajaxSuccess",[x,e])}function d(){e.complete&&e.complete.call(k,x,i);e.global&&f("ajaxComplete",[x,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")}function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),j,i,o,k=a&&a.context||e,n=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(n==="GET")N.test(e.url)||(e.url+=(ka.test(e.url)?
+"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)||N.test(e.url))){j=e.jsonpCallback||"jsonp"+sb++;if(e.data)e.data=(e.data+"").replace(N,"="+j+"$1");e.url=e.url.replace(N,"="+j+"$1");e.dataType="script";A[j]=A[j]||function(q){o=q;b();d();A[j]=w;try{delete A[j]}catch(p){}z&&z.removeChild(C)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache===
+false&&n==="GET"){var r=J(),u=e.url.replace(wb,"$1_="+r+"$2");e.url=u+(u===e.url?(ka.test(e.url)?"&":"?")+"_="+r:"")}if(e.data&&n==="GET")e.url+=(ka.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&&c.event.trigger("ajaxStart");r=(r=xb.exec(e.url))&&(r[1]&&r[1]!==location.protocol||r[2]!==location.host);if(e.dataType==="script"&&n==="GET"&&r){var z=s.getElementsByTagName("head")[0]||s.documentElement,C=s.createElement("script");C.src=e.url;if(e.scriptCharset)C.charset=e.scriptCharset;if(!j){var B=
+false;C.onload=C.onreadystatechange=function(){if(!B&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){B=true;b();d();C.onload=C.onreadystatechange=null;z&&C.parentNode&&z.removeChild(C)}}}z.insertBefore(C,z.firstChild);return w}var E=false,x=e.xhr();if(x){e.username?x.open(n,e.url,e.async,e.username,e.password):x.open(n,e.url,e.async);try{if(e.data||a&&a.contentType)x.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&x.setRequestHeader("If-Modified-Since",
+c.lastModified[e.url]);c.etag[e.url]&&x.setRequestHeader("If-None-Match",c.etag[e.url])}r||x.setRequestHeader("X-Requested-With","XMLHttpRequest");x.setRequestHeader("Accept",e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(ga){}if(e.beforeSend&&e.beforeSend.call(k,x,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");x.abort();return false}e.global&&f("ajaxSend",[x,e]);var g=x.onreadystatechange=function(q){if(!x||x.readyState===0||q==="abort"){E||
+d();E=true;if(x)x.onreadystatechange=c.noop}else if(!E&&x&&(x.readyState===4||q==="timeout")){E=true;x.onreadystatechange=c.noop;i=q==="timeout"?"timeout":!c.httpSuccess(x)?"error":e.ifModified&&c.httpNotModified(x,e.url)?"notmodified":"success";var p;if(i==="success")try{o=c.httpData(x,e.dataType,e)}catch(v){i="parsererror";p=v}if(i==="success"||i==="notmodified")j||b();else c.handleError(e,x,i,p);d();q==="timeout"&&x.abort();if(e.async)x=null}};try{var h=x.abort;x.abort=function(){x&&h.call(x);
+g("abort")}}catch(l){}e.async&&e.timeout>0&&setTimeout(function(){x&&!E&&g("timeout")},e.timeout);try{x.send(n==="POST"||n==="PUT"||n==="DELETE"?e.data:null)}catch(m){c.handleError(e,x,null,m);d()}e.async||g();return x}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status===
+1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]=f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b===
+"json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(i,o){if(c.isArray(o))c.each(o,function(k,n){b||/\[\]$/.test(i)?f(i,n):d(i+"["+(typeof n==="object"||c.isArray(n)?k:"")+"]",n)});else!b&&o!=null&&typeof o==="object"?c.each(o,function(k,n){d(i+"["+k+"]",n)}):f(i,o)}function f(i,o){o=c.isFunction(o)?o():o;e[e.length]=encodeURIComponent(i)+"="+encodeURIComponent(o)}var e=[];if(b===w)b=c.ajaxSettings.traditional;
+if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var j in a)d(j,a[j]);return e.join("&").replace(yb,"+")}});var la={},Ab=/toggle|show|hide/,Bb=/^([+-]=)?([\d+-.]+)(.*)$/,W,va=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");
+this[a].style.display=d||"";if(c.css(this[a],"display")==="none"){d=this[a].nodeName;var f;if(la[d])f=la[d];else{var e=c("<"+d+" />").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove();la[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a<b;a++)this[a].style.display=c.data(this[a],"olddisplay")||"";return this}},hide:function(a,b){if(a||a===0)return this.animate(K("hide",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");!d&&d!=="none"&&c.data(this[a],
+"olddisplay",c.css(this[a],"display"))}a=0;for(b=this.length;a<b;a++)this[a].style.display="none";return this}},_toggle:c.fn.toggle,toggle:function(a,b){var d=typeof a==="boolean";if(c.isFunction(a)&&c.isFunction(b))this._toggle.apply(this,arguments);else a==null||d?this.each(function(){var f=d?a:c(this).is(":hidden");c(this)[f?"show":"hide"]()}):this.animate(K("toggle",3),a,b);return this},fadeTo:function(a,b,d){return this.filter(":hidden").css("opacity",0).show().end().animate({opacity:b},a,d)},
+animate:function(a,b,d,f){var e=c.speed(b,d,f);if(c.isEmptyObject(a))return this.each(e.complete);return this[e.queue===false?"each":"queue"](function(){var j=c.extend({},e),i,o=this.nodeType===1&&c(this).is(":hidden"),k=this;for(i in a){var n=i.replace(ia,ja);if(i!==n){a[n]=a[i];delete a[i];i=n}if(a[i]==="hide"&&o||a[i]==="show"&&!o)return j.complete.call(this);if((i==="height"||i==="width")&&this.style){j.display=c.css(this,"display");j.overflow=this.style.overflow}if(c.isArray(a[i])){(j.specialEasing=
+j.specialEasing||{})[i]=a[i][1];a[i]=a[i][0]}}if(j.overflow!=null)this.style.overflow="hidden";j.curAnim=c.extend({},a);c.each(a,function(r,u){var z=new c.fx(k,j,r);if(Ab.test(u))z[u==="toggle"?o?"show":"hide":u](a);else{var C=Bb.exec(u),B=z.cur(true)||0;if(C){u=parseFloat(C[2]);var E=C[3]||"px";if(E!=="px"){k.style[r]=(u||1)+E;B=(u||1)/z.cur(true)*B;k.style[r]=B+E}if(C[1])u=(C[1]==="-="?-1:1)*u+B;z.custom(B,u,E)}else z.custom(B,u,"")}});return true})},stop:function(a,b){var d=c.timers;a&&this.queue([]);
+this.each(function(){for(var f=d.length-1;f>=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration===
+"number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a,b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]||
+c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(j){return e.step(j)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start;
+this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now=
+this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem,
+e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos=c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b<a.length;b++)a[b]()||a.splice(b--,1);a.length||
+c.fx.stop()},stop:function(){clearInterval(W);W=null},speeds:{slow:600,fast:200,_default:400},step:{opacity:function(a){c.style(a.elem,"opacity",a.now)},_default:function(a){if(a.elem.style&&a.elem.style[a.prop]!=null)a.elem.style[a.prop]=(a.prop==="width"||a.prop==="height"?Math.max(0,a.now):a.now)+a.unit;else a.elem[a.prop]=a.now}}});if(c.expr&&c.expr.filters)c.expr.filters.animated=function(a){return c.grep(c.timers,function(b){return a===b.elem}).length};c.fn.offset="getBoundingClientRect"in s.documentElement?
+function(a){var b=this[0];if(a)return this.each(function(e){c.offset.setOffset(this,a,e)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);var d=b.getBoundingClientRect(),f=b.ownerDocument;b=f.body;f=f.documentElement;return{top:d.top+(self.pageYOffset||c.support.boxModel&&f.scrollTop||b.scrollTop)-(f.clientTop||b.clientTop||0),left:d.left+(self.pageXOffset||c.support.boxModel&&f.scrollLeft||b.scrollLeft)-(f.clientLeft||b.clientLeft||0)}}:function(a){var b=
+this[0];if(a)return this.each(function(r){c.offset.setOffset(this,a,r)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);c.offset.initialize();var d=b.offsetParent,f=b,e=b.ownerDocument,j,i=e.documentElement,o=e.body;f=(e=e.defaultView)?e.getComputedStyle(b,null):b.currentStyle;for(var k=b.offsetTop,n=b.offsetLeft;(b=b.parentNode)&&b!==o&&b!==i;){if(c.offset.supportsFixedPosition&&f.position==="fixed")break;j=e?e.getComputedStyle(b,null):b.currentStyle;
+k-=b.scrollTop;n-=b.scrollLeft;if(b===d){k+=b.offsetTop;n+=b.offsetLeft;if(c.offset.doesNotAddBorder&&!(c.offset.doesAddBorderForTableAndCells&&/^t(able|d|h)$/i.test(b.nodeName))){k+=parseFloat(j.borderTopWidth)||0;n+=parseFloat(j.borderLeftWidth)||0}f=d;d=b.offsetParent}if(c.offset.subtractsBorderForOverflowNotVisible&&j.overflow!=="visible"){k+=parseFloat(j.borderTopWidth)||0;n+=parseFloat(j.borderLeftWidth)||0}f=j}if(f.position==="relative"||f.position==="static"){k+=o.offsetTop;n+=o.offsetLeft}if(c.offset.supportsFixedPosition&&
+f.position==="fixed"){k+=Math.max(i.scrollTop,o.scrollTop);n+=Math.max(i.scrollLeft,o.scrollLeft)}return{top:k,left:n}};c.offset={initialize:function(){var a=s.body,b=s.createElement("div"),d,f,e,j=parseFloat(c.curCSS(a,"marginTop",true))||0;c.extend(b.style,{position:"absolute",top:0,left:0,margin:0,border:0,width:"1px",height:"1px",visibility:"hidden"});b.innerHTML="<div style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;'><div></div></div><table style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;' cellpadding='0' cellspacing='0'><tr><td></td></tr></table>";
+a.insertBefore(b,a.firstChild);d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==j;a.removeChild(b);
+c.offset.initialize=c.noop},bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),j=parseInt(c.curCSS(a,"top",true),10)||0,i=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a,
+d,e);d={top:b.top-e.top+j,left:b.left-e.left+i};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top-
+f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a=this.offsetParent||s.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],j;if(!e)return null;if(f!==w)return this.each(function(){if(j=wa(this))j.scrollTo(!a?f:c(j).scrollLeft(),a?f:c(j).scrollTop());else this[d]=f});else return(j=wa(e))?"pageXOffset"in j?j[a?"pageYOffset":
+"pageXOffset"]:c.support.boxModel&&j.document.documentElement[d]||j.document.body[d]:e[d]}});c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(j){var i=c(this);i[d](f.call(this,j,i[d]()))});return"scrollTo"in
+e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]||e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===w?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});A.jQuery=A.$=c})(window);

docsite/_static/pygments.css

@@ -0,0 +1,62 @@
+.highlight .hll { background-color: #ffffcc }
+.highlight  { background: #eeffcc; }
+.highlight .c { color: #408090; font-style: italic } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #007020; font-weight: bold } /* Keyword */
+.highlight .o { color: #666666 } /* Operator */
+.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #007020 } /* Comment.Preproc */
+.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #303030 } /* Generic.Output */
+.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #0040D0 } /* Generic.Traceback */
+.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #007020 } /* Keyword.Pseudo */
+.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #902000 } /* Keyword.Type */
+.highlight .m { color: #208050 } /* Literal.Number */
+.highlight .s { color: #4070a0 } /* Literal.String */
+.highlight .na { color: #4070a0 } /* Name.Attribute */
+.highlight .nb { color: #007020 } /* Name.Builtin */
+.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
+.highlight .no { color: #60add5 } /* Name.Constant */
+.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
+.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #007020 } /* Name.Exception */
+.highlight .nf { color: #06287e } /* Name.Function */
+.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */
+.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #bb60d5 } /* Name.Variable */
+.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mf { color: #208050 } /* Literal.Number.Float */
+.highlight .mh { color: #208050 } /* Literal.Number.Hex */
+.highlight .mi { color: #208050 } /* Literal.Number.Integer */
+.highlight .mo { color: #208050 } /* Literal.Number.Oct */
+.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
+.highlight .sc { color: #4070a0 } /* Literal.String.Char */
+.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
+.highlight .s2 { color: #4070a0 } /* Literal.String.Double */
+.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
+.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */
+.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
+.highlight .sx { color: #c65d09 } /* Literal.String.Other */
+.highlight .sr { color: #235388 } /* Literal.String.Regex */
+.highlight .s1 { color: #4070a0 } /* Literal.String.Single */
+.highlight .ss { color: #517918 } /* Literal.String.Symbol */
+.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
+.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
+.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
+.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */

docsite/_static/searchtools.js

@@ -0,0 +1,560 @@
+/*
+ * searchtools.js_t
+ * ~~~~~~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilties for the full-text search.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/**
+ * helper function to return a node containing the
+ * search summary for a given text. keywords is a list
+ * of stemmed words, hlwords is the list of normal, unstemmed
+ * words. the first one is used to find the occurance, the
+ * latter for highlighting it.
+ */
+
+jQuery.makeSearchSummary = function(text, keywords, hlwords) {
+  var textLower = text.toLowerCase();
+  var start = 0;
+  $.each(keywords, function() {
+    var i = textLower.indexOf(this.toLowerCase());
+    if (i > -1)
+      start = i;
+  });
+  start = Math.max(start - 120, 0);
+  var excerpt = ((start > 0) ? '...' : '') +
+  $.trim(text.substr(start, 240)) +
+  ((start + 240 - text.length) ? '...' : '');
+  var rv = $('<div class="context"></div>').text(excerpt);
+  $.each(hlwords, function() {
+    rv = rv.highlightText(this, 'highlighted');
+  });
+  return rv;
+}
+
+
+/**
+ * Porter Stemmer
+ */
+var Stemmer = function() {
+
+  var step2list = {
+    ational: 'ate',
+    tional: 'tion',
+    enci: 'ence',
+    anci: 'ance',
+    izer: 'ize',
+    bli: 'ble',
+    alli: 'al',
+    entli: 'ent',
+    eli: 'e',
+    ousli: 'ous',
+    ization: 'ize',
+    ation: 'ate',
+    ator: 'ate',
+    alism: 'al',
+    iveness: 'ive',
+    fulness: 'ful',
+    ousness: 'ous',
+    aliti: 'al',
+    iviti: 'ive',
+    biliti: 'ble',
+    logi: 'log'
+  };
+
+  var step3list = {
+    icate: 'ic',
+    ative: '',
+    alize: 'al',
+    iciti: 'ic',
+    ical: 'ic',
+    ful: '',
+    ness: ''
+  };
+
+  var c = "[^aeiou]";          // consonant
+  var v = "[aeiouy]";          // vowel
+  var C = c + "[^aeiouy]*";    // consonant sequence
+  var V = v + "[aeiou]*";      // vowel sequence
+
+  var mgr0 = "^(" + C + ")?" + V + C;                      // [C]VC... is m>0
+  var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$";    // [C]VC[V] is m=1
+  var mgr1 = "^(" + C + ")?" + V + C + V + C;              // [C]VCVC... is m>1
+  var s_v   = "^(" + C + ")?" + v;                         // vowel in stem
+
+  this.stemWord = function (w) {
+    var stem;
+    var suffix;
+    var firstch;
+    var origword = w;
+
+    if (w.length < 3)
+      return w;
+
+    var re;
+    var re2;
+    var re3;
+    var re4;
+
+    firstch = w.substr(0,1);
+    if (firstch == "y")
+      w = firstch.toUpperCase() + w.substr(1);
+
+    // Step 1a
+    re = /^(.+?)(ss|i)es$/;
+    re2 = /^(.+?)([^s])s$/;
+
+    if (re.test(w))
+      w = w.replace(re,"$1$2");
+    else if (re2.test(w))
+      w = w.replace(re2,"$1$2");
+
+    // Step 1b
+    re = /^(.+?)eed$/;
+    re2 = /^(.+?)(ed|ing)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      re = new RegExp(mgr0);
+      if (re.test(fp[1])) {
+        re = /.$/;
+        w = w.replace(re,"");
+      }
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1];
+      re2 = new RegExp(s_v);
+      if (re2.test(stem)) {
+        w = stem;
+        re2 = /(at|bl|iz)$/;
+        re3 = new RegExp("([^aeiouylsz])\\1$");
+        re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+        if (re2.test(w))
+          w = w + "e";
+        else if (re3.test(w)) {
+          re = /.$/;
+          w = w.replace(re,"");
+        }
+        else if (re4.test(w))
+          w = w + "e";
+      }
+    }
+
+    // Step 1c
+    re = /^(.+?)y$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(s_v);
+      if (re.test(stem))
+        w = stem + "i";
+    }
+
+    // Step 2
+    re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step2list[suffix];
+    }
+
+    // Step 3
+    re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step3list[suffix];
+    }
+
+    // Step 4
+    re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
+    re2 = /^(.+?)(s|t)(ion)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      if (re.test(stem))
+        w = stem;
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1] + fp[2];
+      re2 = new RegExp(mgr1);
+      if (re2.test(stem))
+        w = stem;
+    }
+
+    // Step 5
+    re = /^(.+?)e$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      re2 = new RegExp(meq1);
+      re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+      if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
+        w = stem;
+    }
+    re = /ll$/;
+    re2 = new RegExp(mgr1);
+    if (re.test(w) && re2.test(w)) {
+      re = /.$/;
+      w = w.replace(re,"");
+    }
+
+    // and turn initial Y back to y
+    if (firstch == "y")
+      w = firstch.toLowerCase() + w.substr(1);
+    return w;
+  }
+}
+
+
+/**
+ * Search Module
+ */
+var Search = {
+
+  _index : null,
+  _queued_query : null,
+  _pulse_status : -1,
+
+  init : function() {
+      var params = $.getQueryParameters();
+      if (params.q) {
+          var query = params.q[0];
+          $('input[name="q"]')[0].value = query;
+          this.performSearch(query);
+      }
+  },
+
+  loadIndex : function(url) {
+    $.ajax({type: "GET", url: url, data: null, success: null,
+            dataType: "script", cache: true});
+  },
+
+  setIndex : function(index) {
+    var q;
+    this._index = index;
+    if ((q = this._queued_query) !== null) {
+      this._queued_query = null;
+      Search.query(q);
+    }
+  },
+
+  hasIndex : function() {
+      return this._index !== null;
+  },
+
+  deferQuery : function(query) {
+      this._queued_query = query;
+  },
+
+  stopPulse : function() {
+      this._pulse_status = 0;
+  },
+
+  startPulse : function() {
+    if (this._pulse_status >= 0)
+        return;
+    function pulse() {
+      Search._pulse_status = (Search._pulse_status + 1) % 4;
+      var dotString = '';
+      for (var i = 0; i < Search._pulse_status; i++)
+        dotString += '.';
+      Search.dots.text(dotString);
+      if (Search._pulse_status > -1)
+        window.setTimeout(pulse, 500);
+    };
+    pulse();
+  },
+
+  /**
+   * perform a search for something
+   */
+  performSearch : function(query) {
+    // create the required interface elements
+    this.out = $('#search-results');
+    this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
+    this.dots = $('<span></span>').appendTo(this.title);
+    this.status = $('<p style="display: none"></p>').appendTo(this.out);
+    this.output = $('<ul class="search"/>').appendTo(this.out);
+
+    $('#search-progress').text(_('Preparing search...'));
+    this.startPulse();
+
+    // index already loaded, the browser was quick!
+    if (this.hasIndex())
+      this.query(query);
+    else
+      this.deferQuery(query);
+  },
+
+  query : function(query) {
+    var stopwords = ["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"];
+
+    // Stem the searchterms and add them to the correct list
+    var stemmer = new Stemmer();
+    var searchterms = [];
+    var excluded = [];
+    var hlterms = [];
+    var tmp = query.split(/\s+/);
+    var objectterms = [];
+    for (var i = 0; i < tmp.length; i++) {
+      if (tmp[i] != "") {
+          objectterms.push(tmp[i].toLowerCase());
+      }
+
+      if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) ||
+          tmp[i] == "") {
+        // skip this "word"
+        continue;
+      }
+      // stem the word
+      var word = stemmer.stemWord(tmp[i]).toLowerCase();
+      // select the correct list
+      if (word[0] == '-') {
+        var toAppend = excluded;
+        word = word.substr(1);
+      }
+      else {
+        var toAppend = searchterms;
+        hlterms.push(tmp[i].toLowerCase());
+      }
+      // only add if not already in the list
+      if (!$.contains(toAppend, word))
+        toAppend.push(word);
+    };
+    var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
+
+    // console.debug('SEARCH: searching for:');
+    // console.info('required: ', searchterms);
+    // console.info('excluded: ', excluded);
+
+    // prepare search
+    var filenames = this._index.filenames;
+    var titles = this._index.titles;
+    var terms = this._index.terms;
+    var fileMap = {};
+    var files = null;
+    // different result priorities
+    var importantResults = [];
+    var objectResults = [];
+    var regularResults = [];
+    var unimportantResults = [];
+    $('#search-progress').empty();
+
+    // lookup as object
+    for (var i = 0; i < objectterms.length; i++) {
+      var others = [].concat(objectterms.slice(0,i),
+                             objectterms.slice(i+1, objectterms.length))
+      var results = this.performObjectSearch(objectterms[i], others);
+      // Assume first word is most likely to be the object,
+      // other words more likely to be in description.
+      // Therefore put matches for earlier words first.
+      // (Results are eventually used in reverse order).
+      objectResults = results[0].concat(objectResults);
+      importantResults = results[1].concat(importantResults);
+      unimportantResults = results[2].concat(unimportantResults);
+    }
+
+    // perform the search on the required terms
+    for (var i = 0; i < searchterms.length; i++) {
+      var word = searchterms[i];
+      // no match but word was a required one
+      if ((files = terms[word]) == null)
+        break;
+      if (files.length == undefined) {
+        files = [files];
+      }
+      // create the mapping
+      for (var j = 0; j < files.length; j++) {
+        var file = files[j];
+        if (file in fileMap)
+          fileMap[file].push(word);
+        else
+          fileMap[file] = [word];
+      }
+    }
+
+    // now check if the files don't contain excluded terms
+    for (var file in fileMap) {
+      var valid = true;
+
+      // check if all requirements are matched
+      if (fileMap[file].length != searchterms.length)
+        continue;
+
+      // ensure that none of the excluded terms is in the
+      // search result.
+      for (var i = 0; i < excluded.length; i++) {
+        if (terms[excluded[i]] == file ||
+            $.contains(terms[excluded[i]] || [], file)) {
+          valid = false;
+          break;
+        }
+      }
+
+      // if we have still a valid result we can add it
+      // to the result list
+      if (valid)
+        regularResults.push([filenames[file], titles[file], '', null]);
+    }
+
+    // delete unused variables in order to not waste
+    // memory until list is retrieved completely
+    delete filenames, titles, terms;
+
+    // now sort the regular results descending by title
+    regularResults.sort(function(a, b) {
+      var left = a[1].toLowerCase();
+      var right = b[1].toLowerCase();
+      return (left > right) ? -1 : ((left < right) ? 1 : 0);
+    });
+
+    // combine all results
+    var results = unimportantResults.concat(regularResults)
+      .concat(objectResults).concat(importantResults);
+
+    // print the results
+    var resultCount = results.length;
+    function displayNextItem() {
+      // results left, load the summary and display it
+      if (results.length) {
+        var item = results.pop();
+        var listItem = $('<li style="display:none"></li>');
+        if (DOCUMENTATION_OPTIONS.FILE_SUFFIX == '') {
+          // dirhtml builder
+          var dirname = item[0] + '/';
+          if (dirname.match(/\/index\/$/)) {
+            dirname = dirname.substring(0, dirname.length-6);
+          } else if (dirname == 'index/') {
+            dirname = '';
+          }
+          listItem.append($('<a/>').attr('href',
+            DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
+            highlightstring + item[2]).html(item[1]));
+        } else {
+          // normal html builders
+          listItem.append($('<a/>').attr('href',
+            item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
+            highlightstring + item[2]).html(item[1]));
+        }
+        if (item[3]) {
+          listItem.append($('<span> (' + item[3] + ')</span>'));
+          Search.output.append(listItem);
+          listItem.slideDown(5, function() {
+            displayNextItem();
+          });
+        } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
+          $.get(DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' +
+                item[0] + '.txt', function(data) {
+            if (data != '') {
+              listItem.append($.makeSearchSummary(data, searchterms, hlterms));
+              Search.output.append(listItem);
+            }
+            listItem.slideDown(5, function() {
+              displayNextItem();
+            });
+          }, "text");
+        } else {
+          // no source available, just display title
+          Search.output.append(listItem);
+          listItem.slideDown(5, function() {
+            displayNextItem();
+          });
+        }
+      }
+      // search finished, update title and status message
+      else {
+        Search.stopPulse();
+        Search.title.text(_('Search Results'));
+        if (!resultCount)
+          Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
+        else
+            Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
+        Search.status.fadeIn(500);
+      }
+    }
+    displayNextItem();
+  },
+
+  performObjectSearch : function(object, otherterms) {
+    var filenames = this._index.filenames;
+    var objects = this._index.objects;
+    var objnames = this._index.objnames;
+    var titles = this._index.titles;
+
+    var importantResults = [];
+    var objectResults = [];
+    var unimportantResults = [];
+
+    for (var prefix in objects) {
+      for (var name in objects[prefix]) {
+        var fullname = (prefix ? prefix + '.' : '') + name;
+        if (fullname.toLowerCase().indexOf(object) > -1) {
+          var match = objects[prefix][name];
+          var objname = objnames[match[1]][2];
+          var title = titles[match[0]];
+          // If more than one term searched for, we require other words to be
+          // found in the name/title/description
+          if (otherterms.length > 0) {
+            var haystack = (prefix + ' ' + name + ' ' +
+                            objname + ' ' + title).toLowerCase();
+            var allfound = true;
+            for (var i = 0; i < otherterms.length; i++) {
+              if (haystack.indexOf(otherterms[i]) == -1) {
+                allfound = false;
+                break;
+              }
+            }
+            if (!allfound) {
+              continue;
+            }
+          }
+          var descr = objname + _(', in ') + title;
+          anchor = match[3];
+          if (anchor == '')
+            anchor = fullname;
+          else if (anchor == '-')
+            anchor = objnames[match[1]][1] + '-' + fullname;
+          result = [filenames[match[0]], fullname, '#'+anchor, descr];
+          switch (match[2]) {
+          case 1: objectResults.push(result); break;
+          case 0: importantResults.push(result); break;
+          case 2: unimportantResults.push(result); break;
+          }
+        }
+      }
+    }
+
+    // sort results descending
+    objectResults.sort(function(a, b) {
+      return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
+    });
+
+    importantResults.sort(function(a, b) {
+      return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
+    });
+
+    unimportantResults.sort(function(a, b) {
+      return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
+    });
+
+    return [importantResults, objectResults, unimportantResults]
+  }
+}
+
+$(document).ready(function() {
+  Search.init();
+});

docsite/_static/sidebar.js

@@ -0,0 +1,148 @@
+/*
+ * sidebar.js
+ * ~~~~~~~~~~
+ *
+ * This script makes the Sphinx sidebar collapsible.
+ *
+ * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds
+ * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
+ * used to collapse and expand the sidebar.
+ *
+ * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
+ * and the width of the sidebar and the margin-left of the document
+ * are decreased. When the sidebar is expanded the opposite happens.
+ * This script saves a per-browser/per-session cookie used to
+ * remember the position of the sidebar among the pages.
+ * Once the browser is closed the cookie is deleted and the position
+ * reset to the default (expanded).
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+$(function() {
+  // global elements used by the functions.
+  // the 'sidebarbutton' element is defined as global after its
+  // creation, in the add_sidebar_button function
+  var bodywrapper = $('.bodywrapper');
+  var sidebar = $('.sphinxsidebar');
+  var sidebarwrapper = $('.sphinxsidebarwrapper');
+
+  // original margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar expanded
+  var bw_margin_expanded = bodywrapper.css('margin-left');
+  var ssb_width_expanded = sidebar.width();
+
+  // margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar collapsed
+  var bw_margin_collapsed = '.8em';
+  var ssb_width_collapsed = '.8em';
+
+  // colors used by the current theme
+  var dark_color = $('.related').css('background-color');
+  var light_color = $('.document').css('background-color');
+
+  function sidebar_is_collapsed() {
+    return sidebarwrapper.is(':not(:visible)');
+  }
+
+  function toggle_sidebar() {
+    if (sidebar_is_collapsed())
+      expand_sidebar();
+    else
+      collapse_sidebar();
+  }
+
+  function collapse_sidebar() {
+    sidebarwrapper.hide();
+    sidebar.css('width', ssb_width_collapsed);
+    bodywrapper.css('margin-left', bw_margin_collapsed);
+    sidebarbutton.css({
+        'margin-left': '0',
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('»');
+    sidebarbutton.attr('title', _('Expand sidebar'));
+    document.cookie = 'sidebar=collapsed';
+  }
+
+  function expand_sidebar() {
+    bodywrapper.css('margin-left', bw_margin_expanded);
+    sidebar.css('width', ssb_width_expanded);
+    sidebarwrapper.show();
+    sidebarbutton.css({
+        'margin-left': ssb_width_expanded-12,
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('«');
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    document.cookie = 'sidebar=expanded';
+  }
+
+  function add_sidebar_button() {
+    sidebarwrapper.css({
+        'float': 'left',
+        'margin-right': '0',
+        'width': ssb_width_expanded - 28
+    });
+    // create the button
+    sidebar.append(
+        '<div id="sidebarbutton"><span>&laquo;</span></div>'
+    );
+    var sidebarbutton = $('#sidebarbutton');
+    light_color = sidebarbutton.css('background-color');
+    // find the height of the viewport to center the '<<' in the page
+    var viewport_height;
+    if (window.innerHeight)
+ 	  viewport_height = window.innerHeight;
+    else
+	  viewport_height = $(window).height();
+    sidebarbutton.find('span').css({
+        'display': 'block',
+        'margin-top': (viewport_height - sidebar.position().top - 20) / 2
+    });
+
+    sidebarbutton.click(toggle_sidebar);
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    sidebarbutton.css({
+        'color': '#FFFFFF',
+        'border-left': '1px solid ' + dark_color,
+        'font-size': '1.2em',
+        'cursor': 'pointer',
+        'height': bodywrapper.height(),
+        'padding-top': '1px',
+        'margin-left': ssb_width_expanded - 12
+    });
+
+    sidebarbutton.hover(
+      function () {
+          $(this).css('background-color', dark_color);
+      },
+      function () {
+          $(this).css('background-color', light_color);
+      }
+    );
+  }
+
+  function set_position_from_cookie() {
+    if (!document.cookie)
+      return;
+    var items = document.cookie.split(';');
+    for(var k=0; k<items.length; k++) {
+      var key_val = items[k].split('=');
+      var key = key_val[0];
+      if (key == 'sidebar') {
+        var value = key_val[1];
+        if ((value == 'collapsed') && (!sidebar_is_collapsed()))
+          collapse_sidebar();
+        else if ((value == 'expanded') && (sidebar_is_collapsed()))
+          expand_sidebar();
+      }
+    }
+  }
+
+  add_sidebar_button();
+  var sidebarbutton = $('#sidebarbutton');
+  set_position_from_cookie();
+});

docsite/_static/underscore.js

@@ -0,0 +1,23 @@
+// Underscore.js 0.5.5
+// (c) 2009 Jeremy Ashkenas, DocumentCloud Inc.
+// Underscore is freely distributable under the terms of the MIT license.
+// Portions of Underscore are inspired by or borrowed from Prototype.js,
+// Oliver Steele's Functional, and John Resig's Micro-Templating.
+// For all details and documentation:
+// http://documentcloud.github.com/underscore/
+(function(){var j=this,n=j._,i=function(a){this._wrapped=a},m=typeof StopIteration!=="undefined"?StopIteration:"__break__",b=j._=function(a){return new i(a)};if(typeof exports!=="undefined")exports._=b;var k=Array.prototype.slice,o=Array.prototype.unshift,p=Object.prototype.toString,q=Object.prototype.hasOwnProperty,r=Object.prototype.propertyIsEnumerable;b.VERSION="0.5.5";b.each=function(a,c,d){try{if(a.forEach)a.forEach(c,d);else if(b.isArray(a)||b.isArguments(a))for(var e=0,f=a.length;e<f;e++)c.call(d,
+a[e],e,a);else{var g=b.keys(a);f=g.length;for(e=0;e<f;e++)c.call(d,a[g[e]],g[e],a)}}catch(h){if(h!=m)throw h;}return a};b.map=function(a,c,d){if(a&&b.isFunction(a.map))return a.map(c,d);var e=[];b.each(a,function(f,g,h){e.push(c.call(d,f,g,h))});return e};b.reduce=function(a,c,d,e){if(a&&b.isFunction(a.reduce))return a.reduce(b.bind(d,e),c);b.each(a,function(f,g,h){c=d.call(e,c,f,g,h)});return c};b.reduceRight=function(a,c,d,e){if(a&&b.isFunction(a.reduceRight))return a.reduceRight(b.bind(d,e),c);
+var f=b.clone(b.toArray(a)).reverse();b.each(f,function(g,h){c=d.call(e,c,g,h,a)});return c};b.detect=function(a,c,d){var e;b.each(a,function(f,g,h){if(c.call(d,f,g,h)){e=f;b.breakLoop()}});return e};b.select=function(a,c,d){if(a&&b.isFunction(a.filter))return a.filter(c,d);var e=[];b.each(a,function(f,g,h){c.call(d,f,g,h)&&e.push(f)});return e};b.reject=function(a,c,d){var e=[];b.each(a,function(f,g,h){!c.call(d,f,g,h)&&e.push(f)});return e};b.all=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.every))return a.every(c,
+d);var e=true;b.each(a,function(f,g,h){(e=e&&c.call(d,f,g,h))||b.breakLoop()});return e};b.any=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.some))return a.some(c,d);var e=false;b.each(a,function(f,g,h){if(e=c.call(d,f,g,h))b.breakLoop()});return e};b.include=function(a,c){if(b.isArray(a))return b.indexOf(a,c)!=-1;var d=false;b.each(a,function(e){if(d=e===c)b.breakLoop()});return d};b.invoke=function(a,c){var d=b.rest(arguments,2);return b.map(a,function(e){return(c?e[c]:e).apply(e,d)})};b.pluck=
+function(a,c){return b.map(a,function(d){return d[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);var e={computed:-Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g>=e.computed&&(e={value:f,computed:g})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);var e={computed:Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g<e.computed&&(e={value:f,computed:g})});return e.value};b.sortBy=function(a,c,d){return b.pluck(b.map(a,
+function(e,f,g){return{value:e,criteria:c.call(d,e,f,g)}}).sort(function(e,f){e=e.criteria;f=f.criteria;return e<f?-1:e>f?1:0}),"value")};b.sortedIndex=function(a,c,d){d=d||b.identity;for(var e=0,f=a.length;e<f;){var g=e+f>>1;d(a[g])<d(c)?(e=g+1):(f=g)}return e};b.toArray=function(a){if(!a)return[];if(a.toArray)return a.toArray();if(b.isArray(a))return a;if(b.isArguments(a))return k.call(a);return b.values(a)};b.size=function(a){return b.toArray(a).length};b.first=function(a,c,d){return c&&!d?k.call(a,
+0,c):a[0]};b.rest=function(a,c,d){return k.call(a,b.isUndefined(c)||d?1:c)};b.last=function(a){return a[a.length-1]};b.compact=function(a){return b.select(a,function(c){return!!c})};b.flatten=function(a){return b.reduce(a,[],function(c,d){if(b.isArray(d))return c.concat(b.flatten(d));c.push(d);return c})};b.without=function(a){var c=b.rest(arguments);return b.select(a,function(d){return!b.include(c,d)})};b.uniq=function(a,c){return b.reduce(a,[],function(d,e,f){if(0==f||(c===true?b.last(d)!=e:!b.include(d,
+e)))d.push(e);return d})};b.intersect=function(a){var c=b.rest(arguments);return b.select(b.uniq(a),function(d){return b.all(c,function(e){return b.indexOf(e,d)>=0})})};b.zip=function(){for(var a=b.toArray(arguments),c=b.max(b.pluck(a,"length")),d=new Array(c),e=0;e<c;e++)d[e]=b.pluck(a,String(e));return d};b.indexOf=function(a,c){if(a.indexOf)return a.indexOf(c);for(var d=0,e=a.length;d<e;d++)if(a[d]===c)return d;return-1};b.lastIndexOf=function(a,c){if(a.lastIndexOf)return a.lastIndexOf(c);for(var d=
+a.length;d--;)if(a[d]===c)return d;return-1};b.range=function(a,c,d){var e=b.toArray(arguments),f=e.length<=1;a=f?0:e[0];c=f?e[0]:e[1];d=e[2]||1;e=Math.ceil((c-a)/d);if(e<=0)return[];e=new Array(e);f=a;for(var g=0;1;f+=d){if((d>0?f-c:c-f)>=0)return e;e[g++]=f}};b.bind=function(a,c){var d=b.rest(arguments,2);return function(){return a.apply(c||j,d.concat(b.toArray(arguments)))}};b.bindAll=function(a){var c=b.rest(arguments);if(c.length==0)c=b.functions(a);b.each(c,function(d){a[d]=b.bind(a[d],a)});
+return a};b.delay=function(a,c){var d=b.rest(arguments,2);return setTimeout(function(){return a.apply(a,d)},c)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(b.rest(arguments)))};b.wrap=function(a,c){return function(){var d=[a].concat(b.toArray(arguments));return c.apply(c,d)}};b.compose=function(){var a=b.toArray(arguments);return function(){for(var c=b.toArray(arguments),d=a.length-1;d>=0;d--)c=[a[d].apply(this,c)];return c[0]}};b.keys=function(a){if(b.isArray(a))return b.range(0,a.length);
+var c=[];for(var d in a)q.call(a,d)&&c.push(d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=function(a){return b.select(b.keys(a),function(c){return b.isFunction(a[c])}).sort()};b.extend=function(a,c){for(var d in c)a[d]=c[d];return a};b.clone=function(a){if(b.isArray(a))return a.slice(0);return b.extend({},a)};b.tap=function(a,c){c(a);return a};b.isEqual=function(a,c){if(a===c)return true;var d=typeof a;if(d!=typeof c)return false;if(a==c)return true;if(!a&&c||a&&!c)return false;
+if(a.isEqual)return a.isEqual(c);if(b.isDate(a)&&b.isDate(c))return a.getTime()===c.getTime();if(b.isNaN(a)&&b.isNaN(c))return true;if(b.isRegExp(a)&&b.isRegExp(c))return a.source===c.source&&a.global===c.global&&a.ignoreCase===c.ignoreCase&&a.multiline===c.multiline;if(d!=="object")return false;if(a.length&&a.length!==c.length)return false;d=b.keys(a);var e=b.keys(c);if(d.length!=e.length)return false;for(var f in a)if(!b.isEqual(a[f],c[f]))return false;return true};b.isEmpty=function(a){return b.keys(a).length==
+0};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=function(a){return!!(a&&a.concat&&a.unshift)};b.isArguments=function(a){return a&&b.isNumber(a.length)&&!b.isArray(a)&&!r.call(a,"length")};b.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};b.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};b.isNumber=function(a){return p.call(a)==="[object Number]"};b.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};b.isRegExp=function(a){return!!(a&&
+a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};b.isNaN=function(a){return b.isNumber(a)&&isNaN(a)};b.isNull=function(a){return a===null};b.isUndefined=function(a){return typeof a=="undefined"};b.noConflict=function(){j._=n;return this};b.identity=function(a){return a};b.breakLoop=function(){throw m;};var s=0;b.uniqueId=function(a){var c=s++;return a?a+c:c};b.template=function(a,c){a=new Function("obj","var p=[],print=function(){p.push.apply(p,arguments);};with(obj){p.push('"+a.replace(/[\r\t\n]/g,
+" ").replace(/'(?=[^%]*%>)/g,"\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g,"',$1,'").split("<%").join("');").split("%>").join("p.push('")+"');}return p.join('');");return c?a(c):a};b.forEach=b.each;b.foldl=b.inject=b.reduce;b.foldr=b.reduceRight;b.filter=b.select;b.every=b.all;b.some=b.any;b.head=b.first;b.tail=b.rest;b.methods=b.functions;var l=function(a,c){return c?b(a).chain():a};b.each(b.functions(b),function(a){var c=b[a];i.prototype[a]=function(){var d=b.toArray(arguments);
+o.call(d,this._wrapped);return l(c.apply(b,d),this._chain)}});b.each(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){c.apply(this._wrapped,arguments);return l(this._wrapped,this._chain)}});b.each(["concat","join","slice"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){return l(c.apply(this._wrapped,arguments),this._chain)}});i.prototype.chain=function(){this._chain=true;return this};i.prototype.value=function(){return this._wrapped}})();

docsite/_themes/bootstrap/globaltoc.html

@@ -0,0 +1,5 @@
+<li class="dropdown" data-dropdown="dropdown">
+  <a href="{{ pathto(master_doc) }}"
+     class="dropdown-toggle">Chapter</a>
+  <span class="globaltoc">{{ toctree(maxdepth=1) }}</span>
+</li>

docsite/_themes/bootstrap/layout.html

@@ -0,0 +1,155 @@
+{% extends "basic/layout.html" %}
+{% set script_files = script_files + ['_static/bootstrap-dropdown.js', '_static/bootstrap-scrollspy.js'] %}
+{% set css_files = ['_static/bootstrap.css', '_static/bootstrap-sphinx.css', '_static/ansible-local.css'] + css_files %}
+
+{# Sidebar: Rework into our Boostrap nav section. #}
+{% macro navBar() %}
+  <div class="topbar" data-scrollspy="scrollspy" >
+    <div class="topbar-inner">
+      <div class="container">
+        <!-- <a class="brand" href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a> -->
+        <ul class="nav">
+          {% block sidebartoc %}
+            <li><a href="/">Home</A>
+	    {% include "globaltoc.html" %}
+            {% include "localtoc.html" %}
+          {% endblock %}
+        </ul>
+        <ul class="nav secondary-nav">
+          {% block sidebarsearch %}
+            {% include "searchbox.html" %}
+          {% endblock %}
+        </ul>
+      </div>
+    </div>
+  </div>
+{% endmacro %}
+<p></p>
+
+{%- block extrahead %}
+<script type="text/javascript">
+(function () {
+  /**
+   * Patch TOC list.
+   *
+   * Will mutate the underlying span to have a correct ul for nav.
+   *
+   * @param $span: Span containing nested UL's to mutate.
+   * @param minLevel: Starting level for nested lists. (1: global, 2: local).
+   */
+  var patchToc = function ($span, minLevel) {
+    var $tocList = $("<ul/>").attr('class', "dropdown-menu"),
+      findA;
+
+    // Find all a "internal" tags, traversing recursively.
+    findA = function ($elem, level) {
+      var level = level || 0,
+        $items = $elem.find("> li > a.internal, > ul, > li > ul");
+
+      // Iterate everything in order.
+      $items.each(function (index, item) {
+        var $item = $(item),
+          tag = item.tagName.toLowerCase(),
+          pad = 10 + ((level - minLevel) * 10);
+
+        if (tag === 'a' && level >= minLevel) {
+          // Add to existing padding.
+          $item.css('padding-left', pad + "px");
+          // Add list element.
+          $tocList.append($("<li/>").append($item));
+        } else if (tag === 'ul') {
+          // Recurse.
+          findA($item, level + 1);
+        }
+      });
+    };
+
+    // Start construction and return.
+    findA($span);
+
+    // Wipe out old list and patch in new one.
+    return $span.empty("ul").append($tocList);
+  };
+
+  $(document).ready(function () {
+    // Patch the global and local TOC's to be bootstrap-compliant.
+    patchToc($("span.globaltoc"), 1);
+    patchToc($("span.localtoc"), 2);
+
+    // Activate.
+    $('#topbar').dropdown();
+  });
+}());
+</script>
+
+<script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-29861888-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+   var ga = document.createElement('script'); ga.type =
+'text/javascript'; ga.async = true;
+   ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
+'http://www') + '.google-analytics.com/ga.js';
+   var s = document.getElementsByTagName('script')[0];
+s.parentNode.insertBefore(ga, s);
+ })();
+
+</script>
+<script type="text/javascript">
+// Set the maximum height of drop down menus to just less than the height
+// of the viewport.
+var set_max_menu_height = function () {
+
+  // set menu max height to 75 less than viewport height
+  $('.dropdown-menu').css('max-height', $(window).height() - 75); 
+}
+
+// Set this when we set the page up and on each resize.
+$(window).resize(set_max_menu_height);
+$(window).ready(set_max_menu_height);
+
+</script>
+
+{% endblock %}
+
+{% block header %}{{ navBar() }}{% endblock %}
+
+{# Silence the sidebar's, relbar's #}
+{% block sidebar1 %}{% endblock %}
+{% block sidebar2 %}{% endblock %}
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}
+
+{%- block content %}
+
+<div class="container">
+   {% block body %} {% endblock %}
+<br/>
+</div>
+
+{%- endblock %}
+
+{%- block footer %}
+<footer class="footer">
+<center>
+<a href="http://ansibleworks.com"><img src="http://ansible.cc/img/AnsibleWorks.png" alt="AnsibleWorks"></a>
+<p>
+    {%- if show_copyright %}
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/>
+      {%- else %}
+        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}<br/>
+      {%- endif %}
+    {%- endif %}
+    {%- if last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>
+    {%- endif %}
+    </p>
+</div>
+</center>
+</footer>
+{%- endblock %}
+

docsite/_themes/bootstrap/localtoc.html

@@ -0,0 +1,5 @@
+<li class="dropdown" data-dropdown="dropdown">
+  <a href="#"
+     class="dropdown-toggle">{{ _('Section') }}</a>
+  <span class="localtoc">{{ toc }}</span>
+</li>

docsite/_themes/bootstrap/relations.html

@@ -0,0 +1,8 @@
+{%- if prev %}
+  <li><a href="{{ prev.link|e }}"
+         title="{{ _('previous chapter') }}">{{ "&laquo;"|safe }} {{ prev.title }}</a></li>
+{%- endif %}
+{%- if next %}
+  <li><a href="{{ next.link|e }}"
+         title="{{ _('next chapter') }}">{{ next.title }} {{ "&raquo;"|safe }}</a></li>
+{%- endif %}

docsite/_themes/bootstrap/searchbox.html

@@ -0,0 +1,7 @@
+{%- if pagename != "search" %}
+<form class="pull-left" action="{{ pathto('search') }}" method="get">
+  <input type="text" name="q" placeholder="Search" />
+  <input type="hidden" name="check_keywords" value="yes" />
+  <input type="hidden" name="area" value="default" />
+</form>
+{%- endif %}

docsite/_themes/bootstrap/sourcelink.html

@@ -0,0 +1,4 @@
+{%- if show_source and has_source and sourcename %}
+  <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+         rel="nofollow">{{ _('Source') }}</a></li>
+{%- endif %}

docsite/_themes/bootstrap/static/bootstrap-dropdown.js

@@ -0,0 +1,55 @@
+/* ============================================================
+ * bootstrap-dropdown.js v1.4.0
+ * http://twitter.github.com/bootstrap/javascript.html#dropdown
+ * ============================================================
+ * Copyright 2011 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============================================================ */
+
+
+!function( $ ){
+
+  "use strict"
+
+  /* DROPDOWN PLUGIN DEFINITION
+   * ========================== */
+
+  $.fn.dropdown = function ( selector ) {
+    return this.each(function () {
+      $(this).delegate(selector || d, 'click', function (e) {
+        var li = $(this).parent('li')
+          , isActive = li.hasClass('open')
+
+        clearMenus()
+        !isActive && li.toggleClass('open')
+        return false
+      })
+    })
+  }
+
+  /* APPLY TO STANDARD DROPDOWN ELEMENTS
+   * =================================== */
+
+  var d = 'a.menu, .dropdown-toggle'
+
+  function clearMenus() {
+    $(d).parent('li').removeClass('open')
+  }
+
+  $(function () {
+    $('html').bind("click", clearMenus)
+    $('body').dropdown( '[data-dropdown] a.menu, [data-dropdown] .dropdown-toggle' )
+  })
+
+}( window.jQuery || window.ender );

docsite/_themes/bootstrap/static/bootstrap-scrollspy.js

@@ -0,0 +1,107 @@
+/* =============================================================
+ * bootstrap-scrollspy.js v1.4.0
+ * http://twitter.github.com/bootstrap/javascript.html#scrollspy
+ * =============================================================
+ * Copyright 2011 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============================================================== */
+
+
+!function ( $ ) {
+
+  "use strict"
+
+  var $window = $(window)
+
+  function ScrollSpy( topbar, selector ) {
+    var processScroll = $.proxy(this.processScroll, this)
+    this.$topbar = $(topbar)
+    this.selector = selector || 'li > a'
+    this.refresh()
+    this.$topbar.delegate(this.selector, 'click', processScroll)
+    $window.scroll(processScroll)
+    this.processScroll()
+  }
+
+  ScrollSpy.prototype = {
+
+      refresh: function () {
+        this.targets = this.$topbar.find(this.selector).map(function () {
+          var href = $(this).attr('href')
+          return /^#\w/.test(href) && $(href).length ? href : null
+        })
+
+        this.offsets = $.map(this.targets, function (id) {
+          return $(id).offset().top
+        })
+      }
+
+    , processScroll: function () {
+        var scrollTop = $window.scrollTop() + 10
+          , offsets = this.offsets
+          , targets = this.targets
+          , activeTarget = this.activeTarget
+          , i
+
+        for (i = offsets.length; i--;) {
+          activeTarget != targets[i]
+            && scrollTop >= offsets[i]
+            && (!offsets[i + 1] || scrollTop <= offsets[i + 1])
+            && this.activateButton( targets[i] )
+        }
+      }
+
+    , activateButton: function (target) {
+        this.activeTarget = target
+
+        this.$topbar
+          .find(this.selector).parent('.active')
+          .removeClass('active')
+
+        this.$topbar
+          .find(this.selector + '[href="' + target + '"]')
+          .parent('li')
+          .addClass('active')
+      }
+
+  }
+
+  /* SCROLLSPY PLUGIN DEFINITION
+   * =========================== */
+
+  $.fn.scrollSpy = function( options ) {
+    var scrollspy = this.data('scrollspy')
+
+    if (!scrollspy) {
+      return this.each(function () {
+        $(this).data('scrollspy', new ScrollSpy( this, options ))
+      })
+    }
+
+    if ( options === true ) {
+      return scrollspy
+    }
+
+    if ( typeof options == 'string' ) {
+      scrollspy[options]()
+    }
+
+    return this
+  }
+
+  $(document).ready(function () {
+    $('body').scrollSpy('[data-scrollspy] li > a')
+  })
+
+}( window.jQuery || window.ender );

docsite/_themes/bootstrap/static/bootstrap-sphinx.css_t

@@ -0,0 +1,24 @@
+/*
+* bootstrap-sphinx.css
+* ~~~~~~~~~~~~~~~~~~~~
+*
+* Sphinx stylesheet -- Twitter Bootstrap theme.
+*/
+
+body {
+  padding-top: 42px;
+}
+
+div.documentwrapper {
+  float: left;
+  width: 100%;
+}
+
+{%- block sidebarlogo %}
+  {%- if logo %}
+.topbar h3 a, .topbar .brand {
+  background: transparent url("{{ logo }}") no-repeat 22px 3px;
+  padding-left: 62px;
+}
+  {%- endif %}
+{%- endblock %}

docsite/_themes/bootstrap/theme.conf

@@ -0,0 +1,5 @@
+# Twitter Bootstrap Theme
+[theme]
+inherit = basic
+stylesheet = basic.css
+pygments_style = tango

docsite/build-site.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
+#
+# This file is part of the Ansible Documentation
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+__docformat__ = 'restructuredtext'
+
+import os
+import sys
+import traceback
+try:
+    from sphinx.application import Sphinx
+except ImportError:
+    print "#################################"
+    print "Dependency missing: Python Sphinx"
+    print "#################################"
+    sys.exit(1)
+import os
+
+
+class SphinxBuilder(object):
+    """
+    Creates HTML documentation using Sphinx.
+    """
+
+    def __init__(self):
+        """
+        Run the DocCommand.
+        """
+        print "Creating html documentation ..."
+
+        try:
+            buildername = 'html'
+
+            outdir = os.path.abspath(os.getcwd())
+            # Create the output directory if it doesn't exist
+            if not os.access(outdir, os.F_OK):
+                os.mkdir(outdir)
+
+            doctreedir = os.path.join('./', '.doctrees')
+
+            confdir = os.path.abspath('./')
+            srcdir = os.path.abspath('rst')
+            freshenv = True
+
+            # Create the builder
+            app = Sphinx(srcdir,
+                              confdir,
+                              outdir,
+                              doctreedir,
+                              buildername,
+                              {},
+                              sys.stdout,
+                              sys.stderr,
+                              freshenv)
+
+            app.builder.build_all()
+
+        except ImportError, ie:
+            traceback.print_exc()
+        except Exception, ex:
+            print >> sys.stderr, "FAIL! exiting ... (%s)" % ex
+
+    def build_docs(self):
+        self.app.builder.build_all()
+
+
+def build_rst_docs():
+    docgen = SphinxBuilder()
+
+if __name__ == '__main__':
+    if '-h' in sys.argv or '--help' in sys.argv:
+        print "This script builds the html documentation from rst/asciidoc sources.\n"
+        print "    Run 'make docs' to build everything."
+        print "    Run 'make viewdocs' to build and then preview in a web browser."
+        sys.exit(0)
+
+    # The 'htmldocs' make target will call this scrip twith the 'rst'
+    # parameter' We don't need to run the 'htmlman' target then.
+    if "rst" in sys.argv:
+        build_rst_docs()
+    else:
+        # By default, preform the rst->html transformation and then
+        # the asciidoc->html trasnformation
+        build_rst_docs()
+
+    if "view" in sys.argv:
+        import webbrowser
+        if not webbrowser.open('index.html'):
+            print >> sys.stderr, "Could not open on your webbrowser."

docsite/conf.py

@@ -0,0 +1,206 @@
+# -*- coding: utf-8 -*-
+#
+# documentation build configuration file, created by
+# sphinx-quickstart on Sat Sep 27 13:23:22 2008-2009.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed
+# automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+import os
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+#sys.path.append(os.path.abspath('some/directory'))
+
+sys.path.insert(0, os.path.join('ansible', 'lib'))
+sys.path.append(os.path.abspath('_themes'))
+
+VERSION='0.01'
+AUTHOR='AnsibleWorks'
+
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings.
+# They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc']
+
+# Later on, add 'sphinx.ext.viewcode' to the list if you want to have
+# colorized code generated too for references.
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Ansible Documentation'
+copyright = "2013 AnsibleWorks"
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = VERSION
+# The full version, including alpha/beta/rc tags.
+release = VERSION
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directories, that shouldn't be
+# searched for source files.
+#exclude_dirs = []
+
+# A list of glob-style patterns that should be excluded when looking
+# for source files.
+exclude_patterns = ['modules']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+html_theme_path = ['_themes']
+html_theme = 'bootstrap'
+html_short_title = 'Ansible Documentation'
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = 'Ansible Documentation'
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = 'favicon.ico'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+html_copy_source = False
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Poseidodoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class
+# [howto/manual]).
+latex_documents = [
+  ('index', 'ansible.tex', 'Ansible Documentation',
+   AUTHOR, 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+autoclass_content = 'both'

docsite/man/ansible-playbook.1.html

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-playbook</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-playbook" lang="en"><a id="id474207"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook &lt;filename.yml&gt; … [options]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment
+system.  Ansible-playbook is the tool used to run them.  See the
+project home page (link below) for more information.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
+<span class="strong"><strong>filename.yml</strong></span>
+</span></dt><dd>
+The names of one or more YAML format files to run as ansible playbooks.
+</dd></dl></div></div><div class="refsect1" title="OPTIONS"><a id="_options"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">
+<span class="strong"><strong>-i</strong></span> <span class="emphasis"><em>PATH</em></span>, <span class="strong"><strong>--inventory=</strong></span><span class="emphasis"><em>PATH</em></span>
+</span></dt><dd>
+The <span class="emphasis"><em>PATH</em></span> to the inventory hosts file, which defaults to <span class="emphasis"><em>/etc/ansible/hosts</em></span>.
+</dd><dt><span class="term">
+<span class="strong"><strong>-M</strong></span> <span class="emphasis"><em>DIRECTORY</em></span>, <span class="strong"><strong>--module-path=</strong></span><span class="emphasis"><em>DIRECTORY</em></span>
+</span></dt><dd>
+The <span class="emphasis"><em>DIRECTORY</em></span> to load modules from. The default is <span class="emphasis"><em>/usr/share/ansible</em></span>.
+</dd><dt><span class="term">
+<span class="strong"><strong>-f</strong></span> <span class="emphasis"><em>NUM</em></span>, <span class="strong"><strong>--forks=</strong></span><span class="emphasis"><em>NUM</em></span>
+</span></dt><dd>
+Level of parallelism. <span class="emphasis"><em>NUM</em></span> is specified as an integer, the default is 5.
+</dd><dt><span class="term">
+<span class="strong"><strong>-k</strong></span>, <span class="strong"><strong>--ask-pass</strong></span>
+</span></dt><dd>
+Prompt for the SSH password instead of assuming key-based authentication with ssh-agent.
+</dd><dt><span class="term">
+<span class="strong"><strong>-T</strong></span> <span class="emphasis"><em>SECONDS</em></span>, <span class="strong"><strong>--timeout=</strong></span><span class="emphasis"><em>SECONDS</em></span>
+</span></dt><dd>
+Connection timeout to use when trying to talk to hosts, in <span class="emphasis"><em>SECONDS</em></span>.
+</dd></dl></div></div><div class="refsect1" title="ENVIRONMENT"><a id="_environment"></a><h2>ENVIRONMENT</h2><p>The following environment variables may specified.</p><p>ANSIBLE_HOSTS  — Override the default ansible hosts file</p><p>ANSIBLE_LIBRARY — Override the default ansible module library path</p></div><div class="refsect1" title="AUTHOR"><a id="_author"></a><h2>AUTHOR</h2><p>Ansible was originally written by Michael DeHaan. See the AUTHORS file
+for a complete list of contributors.</p></div><div class="refsect1" title="COPYRIGHT"><a id="_copyright"></a><h2>COPYRIGHT</h2><p>Copyright © 2012, Michael DeHaan</p><p>Ansible is released under the terms of the GPLv3 License.</p></div><div class="refsect1" title="SEE ALSO"><a id="_see_also"></a><h2>SEE ALSO</h2><p><span class="strong"><strong>ansible</strong></span>(1)</p><p>Extensive documentation as well as IRC and mailing list info
+is available on the ansible home page: <a class="ulink" href="https://ansible.github.com/" target="_top">https://ansible.github.com/</a></p></div></div></body></html>

docsite/man/ansible.1.html

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id392901"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
+SSH.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
+<span class="strong"><strong>host-pattern</strong></span>
+</span></dt><dd>
+A name of a group in the inventory file, a shell-like glob selecting
+hosts in inventory file, or any combination of the two separated by
+semicolons.
+</dd></dl></div></div><div class="refsect1" title="OPTIONS"><a id="_options"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term">
+<span class="strong"><strong>-i</strong></span> <span class="emphasis"><em>PATH</em></span>, <span class="strong"><strong>--inventory=</strong></span><span class="emphasis"><em>PATH</em></span>
+</span></dt><dd>
+The <span class="emphasis"><em>PATH</em></span> to the inventory hosts file, which defaults to <span class="emphasis"><em>/etc/ansible/hosts</em></span>.
+</dd><dt><span class="term">
+<span class="strong"><strong>-f</strong></span> <span class="emphasis"><em>NUM</em></span>, <span class="strong"><strong>--forks=</strong></span><span class="emphasis"><em>NUM</em></span>
+</span></dt><dd>
+Level of parallelism. <span class="emphasis"><em>NUM</em></span> is specified as an integer, the default is 5.
+</dd><dt><span class="term">
+<span class="strong"><strong>-m</strong></span> <span class="emphasis"><em>NAME</em></span>, <span class="strong"><strong>--module-name=</strong></span><span class="emphasis"><em>NAME</em></span>
+</span></dt><dd>
+Execute the module called <span class="emphasis"><em>NAME</em></span>.
+</dd><dt><span class="term">
+<span class="strong"><strong>-M</strong></span> <span class="emphasis"><em>DIRECTORY</em></span>, <span class="strong"><strong>--module-path=</strong></span><span class="emphasis"><em>DIRECTORY</em></span>
+</span></dt><dd>
+The <span class="emphasis"><em>DIRECTORY</em></span> to load modules from. The default is <span class="emphasis"><em>/usr/share/ansible</em></span>.
+</dd><dt><span class="term">
+<span class="strong"><strong>-a</strong></span> '<span class="emphasis"><em>ARGUMENTS</em></span>', <span class="strong"><strong>--args=</strong></span>'<span class="emphasis"><em>ARGUMENTS</em></span>'
+</span></dt><dd>
+The <span class="emphasis"><em>ARGUMENTS</em></span> to pass to the module.
+</dd><dt><span class="term">
+<span class="strong"><strong>-k</strong></span>, <span class="strong"><strong>--ask-pass</strong></span>
+</span></dt><dd>
+Prompt for the SSH password instead of assuming key-based authentication with ssh-agent.
+</dd><dt><span class="term">
+<span class="strong"><strong>-o</strong></span>, <span class="strong"><strong>--one-line</strong></span>
+</span></dt><dd>
+Try to output everything on one line.
+</dd><dt><span class="term">
+<span class="strong"><strong>-t</strong></span> <span class="emphasis"><em>DIRECTORY</em></span>, <span class="strong"><strong>--tree=</strong></span><span class="emphasis"><em>DIRECTORY</em></span>
+</span></dt><dd>
+Save contents in this output <span class="emphasis"><em>DIRECTORY</em></span>, with the results saved in a
+file named after each host.
+</dd><dt><span class="term">
+<span class="strong"><strong>-T</strong></span> <span class="emphasis"><em>SECONDS</em></span>, <span class="strong"><strong>--timeout=</strong></span><span class="emphasis"><em>SECONDS</em></span>
+</span></dt><dd>
+Connection timeout to use when trying to talk to hosts, in <span class="emphasis"><em>SECONDS</em></span>.
+</dd><dt><span class="term">
+<span class="strong"><strong>-B</strong></span> <span class="emphasis"><em>NUM</em></span>, <span class="strong"><strong>--background=</strong></span><span class="emphasis"><em>NUM</em></span>
+</span></dt><dd>
+Run commands in the background, killing the task after <span class="emphasis"><em>NUM</em></span> seconds.
+</dd><dt><span class="term">
+<span class="strong"><strong>-P</strong></span> <span class="emphasis"><em>NUM</em></span>, <span class="strong"><strong>--poll=</strong></span><span class="emphasis"><em>NUM</em></span>
+</span></dt><dd>
+Poll a background job every <span class="emphasis"><em>NUM</em></span> seconds. Requires <span class="strong"><strong>-B</strong></span>.
+</dd><dt><span class="term">
+<span class="strong"><strong>-u</strong></span> <span class="emphasis"><em>USERNAME</em></span>, <span class="strong"><strong>--remote-user=</strong></span><span class="emphasis"><em>USERNAME</em></span>
+</span></dt><dd>
+Use this remote <span class="emphasis"><em>USERNAME</em></span> instead of root.
+</dd></dl></div></div><div class="refsect1" title="INVENTORY"><a id="_inventory"></a><h2>INVENTORY</h2><p>Ansible stores the hosts it can potentially operate on in an inventory
+file. The syntax is one host per line.  Groups headers are allowed and
+are included on their own line, enclosed in square brackets.</p></div><div class="refsect1" title="FILES"><a id="_files"></a><h2>FILES</h2><p>/etc/ansible/hosts — Default inventory file</p><p>/usr/share/ansible/ — Default module library</p></div><div class="refsect1" title="ENVIRONMENT"><a id="_environment"></a><h2>ENVIRONMENT</h2><p>The following environment variables may specified.</p><p>ANSIBLE_HOSTS  — Override the default ansible hosts file</p><p>ANSIBLE_LIBRARY — Override the default ansible module library path</p></div><div class="refsect1" title="AUTHOR"><a id="_author"></a><h2>AUTHOR</h2><p>Ansible was originally written by Michael DeHaan. See the AUTHORS file
+for a complete list of contributors.</p></div><div class="refsect1" title="COPYRIGHT"><a id="_copyright"></a><h2>COPYRIGHT</h2><p>Copyright © 2012, Michael DeHaan</p><p>Ansible is released under the terms of the GPLv3 License.</p></div><div class="refsect1" title="SEE ALSO"><a id="_see_also"></a><h2>SEE ALSO</h2><p><span class="strong"><strong>ansible-playbook</strong></span>(1)</p><p>Extensive documentation as well as IRC and mailing list info
+is available on the ansible home page: <a class="ulink" href="https://ansible.github.com/" target="_top">https://ansible.github.com/</a></p></div></div></body></html>

docsite/rst/YAMLSyntax.rst

@@ -0,0 +1,114 @@
+YAML Syntax
+===========
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+This page provides a basic overview of correct YAML syntax, which is how Ansible
+playbooks (our configuration management language) are expressed.  
+
+We use YAML because it is easier to read and write for humans than other common 
+data formats like XML or JSON.  Further, there are libraries available for reading
+and writing YAML in most programming languages.  
+
+You may also wish to read :doc:`playbooks` at the same time to see how this
+is used in practice.
+
+
+YAML Basics
+-----------
+
+For `ansible`, nearly every YAML file starts with a list.   
+Each item in the list is a list of key/value pairs, commonly
+called a "hash" or a "dictionary".  So, we need to know how
+to write lists and dictionaries in YAML.
+
+There's another small quirk to YAML.  All YAML files (regardless of their association with
+`ansible` or not) should start with ``---``.  This is just a YAML
+format thing that means "this is the start of a document".
+
+All members of a list are lines beginning at the same indentation level starting
+with a ``-`` (dash) character::
+
+    ---
+    # A list of tasty fruits
+    - Apple
+    - Orange
+    - Strawberry
+    - Mango
+
+A dictionary is represented in a simple ``key:`` and ``value`` form::
+
+    ---
+    # An employee record
+    name: Example Developer
+    job: Developer
+    skill: Elite
+
+Dictionaries can also be represented in an abbreviated form if you really want to::
+
+    ---
+    # An employee record
+    {name: Example Developer, job: Developer, skill: Elite}
+
+.. _truthiness:
+
+Ansible doesn't really use these too much, but you can also specify a 
+boolean value (true/false) in several forms::
+
+    ---
+    create_key: yes
+    needs_agent: no
+    knows_oop: True
+    likes_emacs: TRUE
+    uses_cvs: false
+
+Let's combine what we learned so far in an arbitary YAML example.  This really
+has nothing to do with Ansible, but will give you a feel for the format::
+
+    ---
+    # An employee record
+    name: Example Developer
+    job: Developer
+    skill: Elite
+    employed: True
+    foods:
+        - Apple
+        - Orange
+        - Strawberry
+        - Mango
+    languages:
+        ruby: Elite
+	python: Elite
+	dotnet: Lame
+
+That's all you really need to know about YAML to get started writing
+`Ansible` playbooks.
+
+Gotchas
+-------
+
+While YAML is generally friendly, the following is going to be a YAML syntax error:
+
+    foo: somebody said I should put a colon here: so I did
+
+You will want to quote any hash values using colons, like so:
+
+    foo: "somebody said I should put a colon here: so I did"
+
+And then the colon will be preserved.
+
+.. seealso::
+
+   :doc:`playbooks`
+       Learn what playbooks can do and how to write/run them.
+   `YAMLLint <http://yamllint.com/>`_
+       YAML Lint (online) helps you debug YAML syntax if you are having problems
+   `Github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_
+       Complete playbook files from the github project source
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+

docsite/rst/api.rst

@@ -0,0 +1,371 @@
+API & Integrations
+==================
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+There are several interesting ways to use Ansible from an API perspective.   You can use
+the Ansible python API to control nodes, you can extend Ansible to respond to various python events,
+and you can plug in inventory data from external data sources.  Ansible is written in its own
+API so you have a considerable amount of power across the board.
+
+.. contents:: `Table of contents`
+   :depth: 2
+   :backlinks: top
+
+Python API
+----------
+
+The Python API is very powerful, and is how the ansible CLI and ansible-playbook
+are implemented.
+
+It's pretty simple::
+
+    import ansible.runner
+
+    runner = ansible.runner.Runner(
+       module_name='ping',
+       module_args='',
+       pattern='web*',
+       forks=10
+    )
+    datastructure = runner.run()
+
+The run method returns results per host, grouped by whether they
+could be contacted or not.  Return types are module specific, as
+expressed in the 'ansible-modules' documentation.::
+
+    {
+        "dark" : {
+           "web1.example.com" : "failure message"
+        }
+        "contacted" : {
+           "web2.example.com" : 1
+        }
+    }
+
+A module can return any type of JSON data it wants, so Ansible can
+be used as a framework to rapidly build powerful applications and scripts.
+
+Detailed API Example
+````````````````````
+
+The following script prints out the uptime information for all hosts::
+
+    #!/usr/bin/python
+
+    import ansible.runner
+    import sys
+
+    # construct the ansible runner and execute on all hosts
+    results = ansible.runner.Runner(
+        pattern='*', forks=10,
+        module_name='command', module_args='/usr/bin/uptime',
+    ).run()
+
+    if results is None:
+       print "No hosts found"
+       sys.exit(1)
+
+    print "UP ***********"
+    for (hostname, result) in results['contacted'].items():
+        if not 'failed' in result:
+            print "%s >>> %s" % (hostname, result['stdout'])
+
+    print "FAILED *******"
+    for (hostname, result) in results['contacted'].items():
+        if 'failed' in result:
+            print "%s >>> %s" % (hostname, result['msg'])
+
+    print "DOWN *********"
+    for (hostname, result) in results['dark'].items():
+        print "%s >>> %s" % (hostname, result)
+
+Advanced programmers may also wish to read the source to ansible itself, for
+it uses the Runner() API (with all available options) to implement the
+command line tools ``ansible`` and ``ansible-playbook``.
+
+Plugins Available Online
+------------------------
+
+The remainder of features in the API docs have components available in `ansible-plugins <https://github.com/ansible/ansible/blob/devel/plugins>`_.  Send us a github pull request if you develop any interesting features.
+
+External Inventory Scripts
+--------------------------
+
+Often a user of a configuration management system will want to keep inventory
+in a different system.  Frequent examples include LDAP, `Cobbler <http://cobbler.github.com>`_,
+or a piece of expensive enterprisey CMDB software.   Ansible easily supports all
+of these options via an external inventory system.  The plugins directory contains some of these already -- including options for EC2/Eucalyptus and OpenStack, which will be detailed below.
+
+It's possible to write an external inventory script in any language.  If you are familiar with Puppet terminology, this concept is basically the same as 'external nodes', with the slight difference that it also defines which hosts are managed.
+
+Script Conventions
+``````````````````
+
+When the external node script is called with the single argument '--list', the script must return a JSON hash/dictionary of all the groups to be managed.
+Each group's value should be either a hash/dictionary containing a list of each host/IP, potential child groups, and potential group variables, or
+simply a list of host/IP addresses, like so::
+
+    {
+        'databases'   : {
+            'hosts'   : [ 'host1.example.com', 'host2.example.com' ],
+            'vars'    : {
+                'a'   : true
+            }
+        },
+        'webservers'  : [ 'host2.example.com', 'host3.example.com' ],
+        'atlanta'     : {
+            'hosts'   : [ 'host1.example.com', 'host4.example.com', 'host5.example.com' ],
+            'vars'    : {
+                'b'   : false
+            },
+            'children': [ 'marietta', '5points' ],
+        },
+        'marietta'    : [ 'host6.example.com' ],
+        '5points'     : [ 'host7.example.com' ]
+    }
+
+.. versionadded: 1.0
+
+Before version 1.0, each group could only have a list of hostnames/IP addresses, like the webservers, marietta, and 5points groups above.
+
+When called with the arguments '--host <hostname>' (where <hostname> is a host from above), the script must return either an empty JSON
+hash/dictionary, or a hash/dictionary of variables to make available to templates and playbooks.  Returning variables is optional,
+if the script does not wish to do this, returning an empty hash/dictionary is the way to go::
+
+    {
+        'favcolor'   : 'red',
+        'ntpserver'  : 'wolf.example.com',
+        'monitoring' : 'pack.example.com'
+    }
+
+Example: The Cobbler External Inventory Script
+``````````````````````````````````````````````
+
+It is expected that many Ansible users will also be `Cobbler <http://cobbler.github.com>`_ users.  Cobbler has a generic
+layer that allows it to represent data for multiple configuration management systems (even at the same time), and has
+been referred to as a 'lightweight CMDB' by some admins.   This particular script will communicate with Cobbler
+using Cobbler's XMLRPC API.
+
+To tie Ansible's inventory to Cobbler (optional), copy `this script <https://raw.github.com/ansible/ansible/devel/plugins/inventory/cobbler.py>`_ to /etc/ansible/hosts and `chmod +x` the file.  cobblerd will now need
+to be running when you are using Ansible.
+
+Test the file by running `./etc/ansible/hosts` directly.   You should see some JSON data output, but it may not have
+anything in it just yet.
+
+Let's explore what this does.  In cobbler, assume a scenario somewhat like the following::
+
+    cobbler profile add --name=webserver --distro=CentOS6-x86_64
+    cobbler profile edit --name=webserver --mgmt-classes="webserver" --ksmeta="a=2 b=3"
+    cobbler system edit --name=foo --dns-name="foo.example.com" --mgmt-classes="atlanta" --ksmeta="c=4"
+    cobbler system edit --name=bar --dns-name="bar.example.com" --mgmt-classes="atlanta" --ksmeta="c=5"
+
+In the example above, the system 'foo.example.com' will be addressable by ansible directly, but will also be addressable when using the group names 'webserver' or 'atlanta'.  Since Ansible uses SSH, we'll try to contract system foo over 'foo.example.com', only, never just 'foo'.  Similarly, if you try "ansible foo" it wouldn't find the system... but "ansible 'foo*'" would, because the system DNS name starts with 'foo'.
+
+The script doesn't just provide host and group info.  In addition, as a bonus, when the 'setup' module is run (which happens automatically when using playbooks), the variables 'a', 'b', and 'c' will all be auto-populated in the templates::
+
+    # file: /srv/motd.j2
+    Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }}
+
+Which could be executed just like this::
+
+    ansible webserver -m setup
+    ansible webserver -m template -a "src=/tmp/motd.j2 dest=/etc/motd"
+
+.. note::
+   The name 'webserver' came from cobbler, as did the variables for
+   the config file.  You can still pass in your own variables like
+   normal in Ansible, but variables from the external inventory script
+   will override any that have the same name.
+
+So, with the template above (motd.j2), this would result in the following data being written to /etc/motd for system 'foo'::
+
+    Welcome, I am templated with a value of a=2, b=3, and c=4
+
+And on system 'bar' (bar.example.com)::
+
+    Welcome, I am templated with a value of a=2, b=3, and c=5
+
+And technically, though there is no major good reason to do it, this also works too::
+
+    ansible webserver -m shell -a "echo {{ a }}"
+
+So in other words, you can use those variables in arguments/actions as well.  You might use this to name
+a conf.d file appropriately or something similar.  Who knows?
+
+So that's the Cobbler integration support -- using the cobbler script as an example, it should be trivial to adapt Ansible to pull inventory, as well as variable information, from any data source.  If you create anything interesting, please share with the mailing list, and we can keep it in the source code tree for others to use.
+
+Example: AWS EC2 External Inventory Script
+``````````````````````````````````````````
+
+If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach. For this reason, you can use the `EC2 external inventory  <https://raw.github.com/ansible/ansible/devel/plugins/inventory/ec2.py>`_ script.
+
+You can use this script in one of two ways. The easiest is to use Ansible's ``-i`` command line option and specify the path to the script.
+
+    ansible -i ec2.py -u ubuntu us-east-1d -m ping
+
+The second option is to copy the script to `/etc/ansible/hosts` and `chmod +x` it. You will also need to copy the `ec2.ini  <https://raw.github.com/ansible/ansible/devel/plugins/inventory/ec2.ini>`_ file to `/etc/ansible/ec2.ini`. Then you can run ansible as you would normally.
+
+To successfully make an API call to AWS, you will need to configure Boto (the Python interface to AWS). There are a `variety of methods <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_ available, but the simplest is just to export two environment variables:
+
+    export AWS_ACCESS_KEY_ID='AK123'
+    export AWS_SECRET_ACCESS_KEY='abc123'
+
+You can test the script by itself to make sure your config is correct
+
+    cd plugins/inventory
+    ./ec2.py --list
+
+After a few moments, you should see your entire EC2 inventory across all regions in JSON.
+
+Since each region requires its own API call, if you are only using a small set of regions, feel free to edit ``ec2.ini`` and list only the regions you are interested in. There are other config options in ``ec2.ini`` including cache control, and destination variables.
+
+At their heart, inventory files are simply a mapping from some name to a destination address. The default ``ec2.ini`` settings are configured for running Ansible from outside EC2 (from your laptop for example). If you are running Ansible from within EC2, internal DNS names and IP addresses may make more sense than public DNS names. In this case, you can modify the ``destination_variable`` in ``ec2.ini`` to be the private DNS name of an instance. This is particularly important when running Ansible within a private subnet inside a VPC, where the only way to access an instance is via its private IP address. For VPC instances, `vpc_destination_variable` in ``ec2.ini`` provides a means of using which ever `boto.ec2.instance variable <http://docs.pythonboto.org/en/latest/ref/ec2.html#module-boto.ec2.instance>`_ makes the most sense for your use case.
+
+The EC2 external inventory provides mappings to instances from several groups:
+
+Instance ID
+  These are groups of one since instance IDs are unique.
+  e.g.
+  ``i-00112233``
+  ``i-a1b1c1d1``
+
+Region
+  A group of all instances in an AWS region.
+  e.g.
+  ``us-east-1``
+  ``us-west-2``
+
+Availability Zone
+  A group of all instances in an availability zone.
+  e.g.
+  ``us-east-1a``
+  ``us-east-1b``
+
+Security Group
+  Instances belong to one or more security groups. A group is created for each security group, with all characters except alphanumerics, dashes (-) converted to underscores (_). Each group is prefixed by ``security_group_``
+  e.g.
+  ``security_group_default``
+  ``security_group_webservers``
+  ``security_group_Pete_s_Fancy_Group``
+
+Tags
+  Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE``
+  e.g.
+  ``tag_Name_Web``
+  ``tag_Name_redis-master-001``
+  ``tag_aws_cloudformation_logical-id_WebServerGroup``
+
+When the Ansible is interacting with a specific server, the EC2 inventory script is called again with the ``--host HOST`` option. This looks up the HOST in the index cache to get the instance ID, and then makes an API call to AWS to get information about that specific instance. It then makes information about that instance available as variables to your playbooks. Each variable is prefixed by ``ec2_``. Here are some of the variables available:
+
+- ec2_architecture
+- ec2_description
+- ec2_dns_name
+- ec2_id
+- ec2_image_id
+- ec2_instance_type
+- ec2_ip_address
+- ec2_kernel
+- ec2_key_name
+- ec2_launch_time
+- ec2_monitored
+- ec2_ownerId
+- ec2_placement
+- ec2_platform
+- ec2_previous_state
+- ec2_private_dns_name
+- ec2_private_ip_address
+- ec2_public_dns_name
+- ec2_ramdisk
+- ec2_region
+- ec2_root_device_name
+- ec2_root_device_type
+- ec2_security_group_ids
+- ec2_security_group_names
+- ec2_spot_instance_request_id
+- ec2_state
+- ec2_state_code
+- ec2_state_reason
+- ec2_status
+- ec2_subnet_id
+- ec2_tag_Name
+- ec2_tenancy
+- ec2_virtualization_type
+- ec2_vpc_id
+
+Both ``ec2_security_group_ids`` and ``ec2_security_group_names`` are comma-separated lists of all security groups. Each EC2 tag is a variable in the format ``ec2_tag_KEY``.
+
+To see the complete list of variables available for an instance, run the script by itself::
+
+    cd plugins/inventory
+    ./ec2.py --host ec2-12-12-12-12.compute-1.amazonaws.com
+
+Example: OpenStack Inventory Script
+```````````````````````````````````
+
+Though not detailed here in as much depth as the EC2 module, there's also a OpenStack Nova external inventory source in the plugins directory.  See the inline comments in the module source for how to use it.
+
+Callback Plugins
+----------------
+
+Ansible can be configured via code to respond to external events.  This can include enhancing logging, signalling an external software
+system, or even (yes, really) making sound effects.  Some examples are contained in the plugins directory.
+
+Connection Type Plugins
+-----------------------
+
+By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection type.  Release 0.8 also
+added an accelerated connection type named 'fireball'.  All of these can be used
+in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.  The basics of these connection types
+are covered in the 'getting started' section.  Should you want to extend Ansible to support other transports (SNMP? Message bus?
+Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
+directory.
+
+Lookup Plugins
+--------------
+
+Language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins.  Just like other plugin types, you can write your own.
+
+Vars Plugins
+------------
+
+Playbook constructs like 'host_vars' and 'group_vars' work via 'vars' plugins.  They inject additional variable
+data into ansible runs that did not come from an inventory, playbook, or command line.  Note that variables
+can also be returned from inventory, so in most cases, you won't need to write or understand vars_plugins.
+
+Filter Plugins
+--------------
+
+If you want more Jinja2 filters available in a Jinja2 template (filters like to_yaml and to_json are provided by default), they can be extended by writing a filter plugin.
+
+Distributing Plugins
+--------------------
+
+.. versionadded: 0.8
+
+Plugins are loaded from both Python's site_packages (those that ship with ansible) and a configured plugins directory, which defaults
+to /usr/share/ansible/plugins, in a subfolder for each plugin type::
+
+    * action_plugins
+    * lookup_plugins
+    * callback_plugins
+    * connection_plugins
+    * filter_plugins
+    * vars_plugins
+
+To change this path, edit the ansible configuration file.
+
+In addition, plugins can be shipped in a subdirectory relative to a top-level playbook, in folders named the same as indicated above.
+
+.. seealso::
+
+   :doc:`modules`
+       List of built-in modules
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+

docsite/rst/bestpractices.rst

@@ -0,0 +1,351 @@
+Best Practices
+==============
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest/
+
+
+Here are some tips for making the most of Ansible.
+
+You can find some example playbooks illustrating these best practices in our `ansible-examples repository <https://github.com/ansible/ansible-examples>`_.
+
+.. contents::
+   :depth: 2
+   :backlinks: top
+
+Content Organization
+++++++++++++++++++++++
+
+The following section shows one of many possible ways to organize content.   Your usage of Ansible should fit your needs,
+so feel free to modify this approach and organize as you see fit.
+
+Directory Layout
+````````````````
+
+The top level of the directory would contain files and directories like so::
+
+    production            # inventory file for production servers
+    stage                 # inventory file for stage environment 
+
+    group_vars/
+       group1             # here we assign variables to particular groups
+       group2             # ""
+    host_vars/
+       hostname1          # if systems need specific variables, put them here
+       hostname2          # ""
+
+    site.yml              # master playbook
+    webservers.yml        # playbook for webserver tier
+    dbservers.yml         # playbook for dbserver tier
+
+    common/               # this hierarchy represents a "role"
+        tasks/            #
+            main.yml      #  <-- tasks file can include smaller files if warranted
+        handlers/         # 
+            main.yml      #  <-- handlers file
+        templates/        #  <-- files for use with the template resource
+            ntp.conf.j2   #  <------- templates end in .j2
+        files/            #
+            bar.txt       #  <-- files for use with the copy resource
+
+    webtier/              # same kind of structure as "common" was above, done for the webtier role
+    monitoring/           # ""
+    fooapp/               # "" 
+
+How to Arrange Inventory, Stage vs Production
+`````````````````````````````````````````````
+
+In this example, the *production* file contains the inventory of all of your production hosts.  Of course you can pull inventory from an external
+data source as well, but this is just a basic example.  Define groups based on purpose of the host (roles) and also geography or datacenter location::
+
+    # file: production
+
+    [atlanta-webservers]
+    www-atl-1.example.com
+    www-atl-2.example.com
+
+    [boston-webservers]
+    www-bos-1.example.com
+    www-bos-2.example.com
+
+    [atlanta-dbservers]
+    db-atl-1.example.com
+    db-atl-2.example.com
+
+    [boston-dbservers]
+    db-bos-1.example.com
+
+    # webservers in all geos
+    [webservers:children]
+    atlanta-webservers
+    boston-webservers
+
+    # dbservers in all geos
+    [dbservers:children]
+    atlanta-dbservers
+    boston-dbservers
+
+    # everything in the atlanta geo
+    [atlanta:children]
+    atlanta-webservers
+    atlanta-dbservers
+
+    # everything in the boston geo
+    [boston:children]
+    boston-webservers
+    boston-dbservers
+
+Group And Host Variables
+````````````````````````
+
+Now, groups are nice for organization, but that's not all groups are good for.  You can also assign variables to them!  For instance, atlanta
+has it's own NTP servers, so when settings up ntp.conf, we should use them.  Let's set those now::
+
+    ---
+    # file: group_vars/atlanta
+    ntp: ntp-atlanta.example.com
+    backup: backup-atlanta.example.com
+
+Variables aren't just for geographic information either!  Maybe the webservers have some configuration that doesn't make sense for the database
+servers::
+
+    ---
+    # file: group_vars/webservers
+    apacheMaxRequestsPerChild: 3000
+    apacheMaxClients: 900
+
+If we had any default values, or values that were universally true, we would put them in a file called group_vars/all::
+
+    ---
+    # file: group_vars/all
+    ntp: ntp-boston.example.com
+    backup: backup-boston.example.com 
+
+We can define specific hardware variance in systems in a host_vars file, but avoid doing this unless you need to::
+
+    ---
+    # file: host_vars/db-bos-1.example.com
+    foo_agent_port: 86
+    bar_agent_port: 99
+
+Top Level Playbooks Are Seperated By Role
+`````````````````````````````````````````
+
+In site.yml, we include a playbook that defines our entire infrastructure.  Note this is SUPER short, because it's just including
+some other playbooks.  Remember playbooks are nothing more than lists of plays::
+
+    ---
+    # file: site.yml
+    - include: webservers.yml
+    - include: dbservers.yml
+
+In a file like webservers.yml (also at the top level), we simply map the configuration of the webservers group to the roles performed by the webservers group.  Also notice this is incredibly short.  For example::
+
+    ---
+    # file: webservers.yml
+    - hosts: webservers
+      tasks:
+        - include: common/tasks/main.yml tags=common
+        - include: webtier/tasks/main.yml tags=webtier
+      handlers:
+        - include: common/handlers/main.yml
+        - include: webtier/handlers/main.yml     
+
+Task And Handler Organization For A Role
+````````````````````````````````````````
+
+This file is just mapping hosts to the roles they fulfill.  Now, below is an example tasks file, that explains how a role works.  Our common role here just sets up NTP, but it could do more if we wanted::
+
+    ---
+    # file: common/tasks/main.yml
+
+    - name: be sure ntp is installed
+      yum: pkg=ntp state=installed
+      tags: ntp
+
+    - name: be sure ntp is configured
+      template: src=common/templates/ntp.conf.j2 dest=/etc/ntp.conf
+      notify:
+        - restart ntpd
+      tags: ntp
+
+    - name: be sure ntpd is running and enabled
+      service: name=ntpd state=running enabled=yes
+      tags: ntp
+
+Here is an example handlers file.  As a review, handlers are only fired when certain tasks report changes, and are run at the end
+of each play::
+
+    ---
+    # file: common/handlers/main.yml
+    - name: restart ntpd
+      service: name=ntpd state=restarted
+
+What This Organization Enables (Examples)
+`````````````````````````````````````````
+
+So that's our basic organizational structure.
+
+Now what sort of use cases does this layout enable?  Lots!  If I want to reconfigure my whole infrastructure, it's just::
+
+    ansible-playbook -i production site.yml
+
+What about just reconfiguring NTP on everything?  Easy.::
+
+    ansible-playbook -i production site.yml --tags ntp
+
+What about just reconfiguring my webservers?::
+
+    ansible-playbook -i production webservers.yml
+
+What about just my webservers in Boston?::
+
+    ansible-playbook -i production webservers.yml --limit boston
+
+What about just the first 10, and then the next 10?::
+   
+    ansible-playbook -i production webservers.yml --limit boston[0-10]
+    ansible-playbook -i production webservers.yml --limit boston[10-20]
+
+And of course just basic ad-hoc stuff is also possible.::
+
+    ansible -i production -m ping
+    ansible -i production -m command -a '/sbin/reboot' --limit boston 
+
+And there are some useful commands (at least in 1.1 to know)::
+
+    # confirm what task names would be run if I ran this command and said "just ntp tasks"
+    ansible-playbook -i production webservers.yml --tags ntp --list-tasks
+
+    # confirm what hostnames might be communicated with if I said "limit to boston"
+    ansible-playbook -i production webservers.yml --limit boston --list-hosts
+
+Deployment vs Configuration Organization
+````````````````````````````````````````
+
+The above setup models a typical OS configuration topology.  When doing multi-tier deployments, there are going
+to be some additional playbooks that hop between tiers to roll out an application.  In this case, 'site.yml'
+may be augmented by playbooks like 'deploy_exampledotcom.yml' but the general concepts can still apply.
+
+Ansible allows you to deploy and configure using the same tool, so you would likely reuse groups and just
+keep the OS configuration in seperate playbooks from the app deployment.
+
+Stage vs Production
++++++++++++++++++++
+
+As also mentioned above, a good way to keep your stage (or testing) and production environments seperate is to use a seperate inventory file for stage
+and production.   This way you pick with -i what you are targetting.  Keeping them all in one file can lead to surprises!
+
+Testing things in a stage environment before trying in production is always a great idea.  Your environments need not be the same
+size and you can use group variables to control the differences between those environments.
+
+Rolling Updates
++++++++++++++++
+
+Understand the 'serial' keyword.  If updating a webserver farm you really want to use it to control how many machines you are
+updating at once in the batch.
+
+Always Mention The State
+++++++++++++++++++++++++
+
+The 'state' parameter is optional to a lot of modules.  Whether 'state=present' or 'state=absent', it's always best to leave that
+parameter in your playbooks to make it clear, especially as some modules support additional states.
+
+Group By Roles
+++++++++++++++
+
+A system can be in multiple groups.  See :doc:`patterns`.   Having groups named after things like
+*webservers* and *dbservers* is repeated in the examples because it's a very powerful concept.
+
+This allows playbooks to target machines based on role, as well as to assign role specific variables
+using the group variable system.
+
+Operating System and Distribution Variance
+++++++++++++++++++++++++++++++++++++++++++
+
+When dealing with a parameter that is different between two different operating systems, the best way to handle this is
+by using the group_by module.
+
+This makes a dynamic group of hosts matching certain criteria, even if that group is not defined in the inventory file::
+
+   ---
+
+   # talk to all hosts just so we can learn about them 
+
+   - hosts: all
+     tasks:
+        - group_by: key=${ansible_distribution}
+
+   # now just on the CentOS hosts...
+
+   - hosts: CentOS
+     gather_facts: False
+     tasks:
+        - # tasks that only happen on CentOS go here
+
+If group specific settings are needed, this can also be done, for example::
+
+    ---
+    # file: group_vars/all
+    asdf: 10
+
+    ---
+    # file: group_vars/CentOS
+    asdf: 42
+
+In the above example, CentOS machines get the value of '42' for asdf, but other machines get 10.
+
+
+Bundling Ansible Modules With Playbooks
++++++++++++++++++++++++++++++++++++++++
+
+.. versionadded:: 0.5
+
+If a playbook has a "./library" directory relative to it's YAML file, this directory can be used to add ansible modules that will
+automatically be in the ansible module path.  This is a great way to keep modules that go with a playbook together.
+
+Whitespace and Comments
++++++++++++++++++++++++
+
+Generous use of whitespace to break things up, and use of comments (which start with '#'), is encouraged.
+
+Always Name Tasks
++++++++++++++++++
+
+It is possible to leave off the 'name' for a given task, though it is recommended to provide a description 
+about why something is being done instead.  This name is shown when the playbook is run.
+
+Keep It Simple
+++++++++++++++
+
+When you can do something simply, do something simply.  Do not reach
+to use every feature of Ansible together, all at once.  Use what works
+for you.  For example, you should probably not need 'vars',
+'vars_files', 'vars_prompt' and '--extra-vars' all at once,
+while also using an external inventory file.
+
+Version Control
++++++++++++++++
+
+Use version control.  Keep your playbooks and inventory file in git
+(or another version control system), and commit when you make changes
+to them.  This way you have an audit trail describing when and why you
+changed the rules automating your infrastructure.
+
+.. seealso::
+
+   :doc:`YAMLSyntax`
+       Learn about YAML syntax
+   :doc:`playbooks`
+       Review the basic playbook features
+   :doc:`modules`
+       Learn about available modules
+   :doc:`moduledev`
+       Learn how to extend Ansible by writing your own modules
+   :doc:`patterns`
+       Learn about how to select hosts
+   `Github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_
+       Complete playbook files from the github project source
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups

docsite/rst/contrib.rst

@@ -0,0 +1,101 @@
+Ansible Resources
+=================
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+User contributed playbooks, modules, and articles. This is a small
+curated list, but growing. Everyone is encouraged to add to this
+document, just send in a github pull request to docsite/rst/contrib.rst!
+
+Ansible Modules
+```````````````
+
+Ansible modules are a way of adding new client-side logic to ansible.
+They can be written in any language.  Generally our goal is to include most modules in core ("batteries included!"),
+though a few may remain outside of core depending on use cases and implementations.
+
+-  `Official "core" ansible modules <http://ansible.cc/docs/modules.html>`_ - various
+-  `Linode <https://github.com/lextoumbourou/ansible-linode>`_ - Lex Toumbourou
+-  `zypper (bash module example) <https://github.com/jpmens/ansible-zypp>`_ - jp\_mens
+-  `additional provisioning-related modules <https://github.com/ansible-provisioning>`_ - jhoekx and dagwieers
+-  `dynamic dns updates <https://github.com/jpmens/ansible-m-dnsupdate>`_ - jp\_mens
+
+All python modules should use the common "AnsibleModule" class to dramatically reduce the amount of boilerplate code required.
+Not all modules above may take advantage of this feature. See the official documentation for more details.
+
+Selected Playbooks
+``````````````````
+
+`Playbooks <http://ansible.cc/docs/playbooks.html>`_ are Ansible's
+configuration management language. It should be easy to write your own
+from scratch for most applications, but it's always helpful to look at
+what others have done for reference.
+
+-  `Hadoop <https://github.com/jkleint/ansible-hadoop>`_ - jkleint
+-  `LAMP <https://github.com/fourkitchens/server-playbooks>`_ - `Four Kitchens <http://fourkitchens.com>`_
+-  `LEMP <https://github.com/francisbesset/ansible-playbooks>`_ - francisbesset
+-  `Ganglia (demo) <https://github.com/mpdehaan/ansible-examples>`_ - mpdehaan
+-  `Nginx <http://www.capsunlock.net/2012/04/ansible-nginx-playbook.html>`_ - cocoy
+-  `OpenStack <http://github.com/lorin/openstack-ansible>`_ - lorin
+-  `Systems Configuration <https://github.com/cegeddin/ansible-contrib>`_ - cegeddin
+-  `Fedora Infrastructure <http://infrastructure.fedoraproject.org/cgit/ansible.git/tree/>`_ - `Fedora <http://fedoraproject.org>`_
+
+Callbacks and Plugins
+`````````````````````
+
+The Ansible project has a whole repo devoted to extending ansible with
+new connection types, logging/event callbacks, and inventory data
+storage. Talk to Cobbler and EC2, tweak the way things are logged, or
+even add sound effects.
+
+-  `Ansible-Plugins <https://github.com/ansible/ansible/tree/devel/plugins>`_
+
+Scripts And Misc
+````````````````
+
+Ansible isn't just a program, it's also an API. Here's some examples of
+some clever integrations with the "Runner" and also Playbook APIs, and
+integrations with other interesting pieces of software.
+
+-  `Ansible Vagrant plugin <https://github.com/dsander/vagrant-ansible>`_ - dsander
+-  `Ansible+Vagrant Tutorial <https://github.com/mattupstate/vagrant-ansible-tutorial>`_ - mattupstate -
+-  `virt-install <http://fedorapeople.org/cgit/skvidal/public_git/scripts.git/tree/ansible/start-prov-boot.py>`_ - skvidal
+-  `rebooting hosts <http://fedorapeople.org/cgit/skvidal/public_git/scripts.git/tree/ansible/host-reboot>`_ - skvidal
+-  `uptime (API demo) <https://github.com/ansible/ansible/blob/devel/examples/scripts/uptime.py>`_ - mpdehaan
+-  `vim snippet generator <https://github.com/bleader/ansible_snippet_generator>`_ - bleader
+
+Blogs, Videos & Articles
+````````````````````````
+
+-  `HighScalability.com <http://highscalability.com/blog/2012/4/18/ansible-a-simple-model-driven-configuration-management-and-c.html>`_ - mpdehaan
+-  `ColoAndCloud.com interview <http://www.coloandcloud.com/editorial/an-interview-with-ansible-author-michael-dehaan/>`_ - mpdehaan
+-  `dzone <http://server.dzone.com/articles/ansible-cm-deployment-and-ad>`_ - Mitch Pronschinske
+-  `Configuration Management With Ansible <http://jpmens.net/2012/06/06/configuration-management-with-ansible/>`_ - jp\_mens
+-  `Shell Scripts As Ansible Modules <http://jpmens.net/2012/07/05/shell-scripts-as-ansible-modules/>`_ - jp\_mens
+-  `Ansible Facts <http://jpmens.net/2012/07/15/ansible-it-s-a-fact/>`_ - jp\_mens
+-  `Infrastructure as Data <http://www.capsunlock.net/2012/04/ansible-infrastructure-as-data-not-infrastructure-as-code.html>`_ - cocoy
+-  `Ansible Pull Mode <http://www.capsunlock.net/2012/05/using-ansible-pull-and-user-data-to-setup-ec2-or-openstack-servers.html>`_ - cocoy
+-  `Exploring Configuration Management With Ansible <http://palominodb.com/blog/2012/08/01/exploring-configuration-management-ansible>`_ - Palamino DB
+-  `You Should Consider Using SSH Based Configuration Management <http://www.lshift.net/blog/2012/07/30/you-should-consider-using-ssh-based-configuration-management>`_ - LShift Ltd
+-  `Deploying Flask/uWSGI, Nginx, and Supervisorctl <http://mattupstate.github.com/python/devops/2012/08/07/flask-wsgi-application-deployment-with-ubuntu-ansible-nginx-supervisor-and-uwsgi.html>`_ - mattupstate
+-  `Infracoders Presentation <http://www.danielhall.me/2012/10/ansible-talk-infra-coders/>`_ - Daniel Hall
+-  `Ansible - an introduction <https://speakerdeck.com/jpmens/ansible-an-introduction>`_ - jp\_mens
+-  `Using Ansible to setup complex networking - <http://exarv.nl/2013/02/using-ansible-to-setup-complex-networking/>`_ - Robert Verspuy
+-  `Video presentation to Montreal Linux <http://www.youtube.com/embed/up3ofvQNm8c>`_ - Alexandre Bourget
+-  `Provisioning CentOS EC2 Instances with Ansible <http://jpmens.net/2012/11/21/provisioning-centos-ec2-instances-with-ansible/>`_ - jp\_mens
+
+Disclaimer
+``````````
+
+Modules and playbooks here may not be using the latest in Ansible
+features. When in doubt to the features of a particular version of
+Ansbile, always consult `ansible.cc <http://ansible.cc>`_ and in
+particular see `Best Practices <http://ansible.cc/docs/bestpractices.html>`_ for some tips
+and tricks that may be useful.
+
+Ansible is (C) 2012, `Michael DeHaan <http://twitter.com/laserllama>`_
+and others and is available under the GPLv3 license. Content here is as
+specified by individual contributors.

docsite/rst/examples.rst

@@ -0,0 +1,269 @@
+Command Line Examples And Next Steps
+====================================
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+.. highlight:: bash
+
+The following examples show how to use `/usr/bin/ansible` for running
+ad hoc tasks.  Start here.
+
+For configuration management and deployments, you'll want to pick up on
+using `/usr/bin/ansible-playbook` -- the concepts port over directly.
+(See :doc:`playbooks` for more information about those)
+
+.. contents::
+   :depth: 2
+   :backlinks: top
+
+
+Parallelism and Shell Commands
+``````````````````````````````
+
+Let's use ansible's command line tool to reboot all web servers in Atlanta, 10 at a time.  First, let's
+set up SSH-agent so it can remember our credentials::
+
+    $ ssh-agent bash
+    $ ssh-add ~/.ssh/id_rsa
+
+If you don't want to use ssh-agent and want to instead SSH with a
+password instead of keys, you can with ``--ask-pass`` (``-k``), but
+it's much better to just use ssh-agent.
+
+Now to run the command on all servers in a group, in this case,
+*atlanta*, in 10 parallel forks::
+
+    $ ansible atlanta -a "/sbin/reboot" -f 10
+
+In 0.7 and later, this will default to running from your user account.  If you do not like this
+behavior, pass in "-u username".  (In 0.6 and before, it defaulted to root.  Most folks prefered
+defaulting to the current user, so we changed it).
+
+If you want to run commands as a different user, it looks like this::
+
+    $ ansible atlanta -a "/usr/bin/foo" -u username
+
+If you want to run commands through sudo::
+
+    $ ansible atlanta -a "/usr/bin/foo" -u username --sudo [--ask-sudo-pass]
+
+Use ``--ask-sudo-pass`` (``-K``) if you are not using passwordless
+sudo.  This will interactively prompt you for the password to use.
+Use of passwordless sudo makes things easier to automate, but it's not
+required.
+
+It is also possible to sudo to a user other than root using
+``--sudo-user`` (``-U``)::
+
+    $ ansible atlanta -a "/usr/bin/foo" -u username -U otheruser [--ask-sudo-pass]
+
+Ok, so those are basics.  If you didn't read about patterns and groups yet, go back and read :doc:`patterns`.
+
+The ``-f 10`` in the above specifies the usage of 10 simultaneous
+processes.  Normally commands also take a ``-m`` for module name, but
+the default module name is 'command', so we didn't need to
+specify that all of the time.  We'll use ``-m`` in later examples to
+run some other :doc:`modules`.
+
+.. note::
+   The :ref:`command` module requires absolute paths and does not
+   support shell variables.  If we want to execute a module using a
+   shell, we can do those things, and also use pipe and redirection
+   operators.  Read more about the differences on the :doc:`modules`
+   page.
+
+Using the :ref:`shell` module looks like this::
+
+    $ ansible raleigh -m shell -a 'echo $TERM'
+
+When running any command with the ansible *ad hoc* CLI (as opposed to
+:doc:`playbooks`), pay particular attention to shell quoting rules, so
+the shell doesn't eat a variable before it gets passed to Ansible.
+For example, using double vs single quotes in the above example would
+evaluate the variable on the box you were on.
+
+So far we've been demoing simple command execution, but most Ansible modules usually do not work like
+simple scripts. They make the remote system look like you state, and run the commands necessary to
+get it there.  This is commonly referred to as 'idempotence', and is a core design goal of ansible.
+However, we also recognize that running *ad hoc* commands is equally important, so Ansible easily supports both.
+
+
+File Transfer
+`````````````
+
+Here's another use case for the `/usr/bin/ansible` command line.  Ansible can SCP lots of files to multiple machines in parallel.
+
+To transfer a file directly to many different servers::
+
+    $ ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"
+
+If you use playbooks, you can also take advantage of the ``template`` module,
+which takes this another step further.  (See module and playbook documentation).
+
+The ``file`` module allows changing ownership and permissions on files.  These
+same options can be passed directly to the ``copy`` module as well::
+
+    $ ansible webservers -m file -a "dest=/srv/foo/a.txt mode=600"
+    $ ansible webservers -m file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"
+
+The ``file`` module can also create directories, similar to ``mkdir -p``::
+
+    $ ansible webservers -m file -a "dest=/path/to/c mode=644 owner=mdehaan group=mdehaan state=directory"
+
+As well as delete directories (recursively) and delete files::
+
+    $ ansible webservers -m file -a "dest=/path/to/c state=absent"
+
+
+Managing Packages
+`````````````````
+
+There are modules available for yum and apt.  Here are some examples
+with yum.
+
+Ensure a package is installed, but don't update it::
+
+    $ ansible webservers -m yum -a "name=acme state=installed"
+
+Ensure a package is installed to a specific version::
+
+    $ ansible webservers -m yum -a "name=acme-1.5 state=installed"
+
+Ensure a package is at the latest version::
+
+    $ ansible webservers -m yum -a "name=acme state=latest"
+
+Ensure a package is not installed::
+
+    $ ansible webservers -m yum -a "name=acme state=removed"
+
+Currently Ansible only has modules for managing packages with yum and apt.  You can install
+for other packages for now using the command module or (better!) contribute a module
+for other package managers.  Stop by the mailing list for info/details.
+
+Users and Groups
+````````````````
+
+The 'user' module allows easy creation and manipulation of
+existing user accounts, as well as removal of user accounts that may
+exist::
+
+    $ ansible all -m user -a "name=foo password=<crypted password here>"
+
+    $ ansible all -m user -a "name=foo state=absent"
+
+See the :doc:`modules` section for details on all of the available options, including
+how to manipulate groups and group membership.
+
+Deploying From Source Control
+`````````````````````````````
+
+Deploy your webapp straight from git::
+
+    $ ansible webservers -m git -a "repo=git://foo.example.org/repo.git dest=/srv/myapp version=HEAD"
+
+Since ansible modules can notify change handlers it is possible to
+tell ansible to run specific tasks when the code is updated, such as
+deploying Perl/Python/PHP/Ruby directly from git and then restarting
+apache.
+
+Managing Services
+`````````````````
+
+Ensure a service is started on all webservers::
+
+    $ ansible webservers -m service -a "name=httpd state=started"
+
+Alternatively, restart a service on all webservers::
+
+    $ ansible webservers -m service -a "name=httpd state=restarted"
+
+Ensure a service is stopped::
+
+    $ ansible webservers -m service -a "name=httpd state=stopped"
+
+Time Limited Background Operations
+``````````````````````````````````
+
+Long running operations can be backgrounded, and their status can be
+checked on later. The same job ID is given to the same task on all
+hosts, so you won't lose track.  If you kick hosts and don't want
+to poll, it looks like this::
+
+    $ ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff"
+
+If you do decide you want to check on the job status later, you can::
+
+    $ ansible all -m async_status -a "jid=123456789"
+
+Polling is built-in and looks like this::
+
+    $ ansible all -B 1800 -P 60 -a "/usr/bin/long_running_operation --do-stuff"
+
+The above example says "run for 30 minutes max (``-B``: 30*60=1800),
+poll for status (``-P``) every 60 seconds".
+
+Poll mode is smart so all jobs will be started before polling will begin on any machine.
+Be sure to use a high enough ``--forks`` value if you want to get all of your jobs started
+very quickly. After the time limit (in seconds) runs out (``-B``), the process on
+the remote nodes will be terminated.
+
+Typically you'll be only be backgrounding long-running
+shell commands or software upgrades only.  Backgrounding the copy module does not do a background file transfer.  :doc:`playbooks` also support polling, and have a simplified syntax for this.
+
+Limiting Selected Hosts
+```````````````````````
+
+.. versionadded:: 0.7
+
+What hosts you select to manage can be additionally constrained by using the '--limit' parameter or
+by using 'batch' (or 'range') selectors.
+
+As mentioned above, patterns can be strung together to select hosts in more than one group::
+
+    $ ansible webservers:dbservers -m command -a "/bin/foo xyz"
+
+This is an "or" condition.  If you want to further constrain the selection, use --limit, which
+also works with ``ansible-playbook``::
+
+    $ ansible webservers:dbservers -m command -a "/bin/foo xyz" --limit region
+
+Assuming version 0.9 or later, as with other host patterns, values to limit can be separated with ";", ":", or ",".
+
+Now let's talk about range selection.   Suppose you have 1000 servers in group 'datacenter', but only want to target one at a time.  This is also easy::
+
+    $ ansible webservers[0-99] -m command -a "/bin/foo xyz"
+    $ ansible webservers[100-199] -m command -a "/bin/foo xyz"
+
+This will select the first 100, then the second 100, host entries in the webservers group.  (It does not matter
+what their names or IP addresses are).
+
+Both of these methods can be used at the same time, and ranges can also be passed to the --limit parameter.
+
+Configuration & Defaults
+````````````````````````
+
+.. versionadded:: 0.7
+
+Ansible has an optional configuration file that can be used to tune settings and also eliminate the need to pass various command line flags. Ansible will look for the config file in the following order, using
+the first config file it finds present:
+
+1. File specified by the ``ANSIBLE_CONFIG`` environment variable
+2. ``ansible.cfg`` in the current working directory. (version 0.8 and up)
+3. ``~/.ansible.cfg``
+4. ``/etc/ansible/ansible.cfg``
+
+For those running from source, a sample configuration file lives in the examples/ directory.  The RPM will install configuration into /etc/ansible/ansible.cfg automatically.
+
+.. seealso::
+
+   :doc:`modules`
+       A list of available modules
+   :doc:`playbooks`
+       Using ansible for configuration management & deployment
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel

docsite/rst/gettingstarted.rst

@@ -0,0 +1,320 @@
+Getting Started
+===============
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+.. contents::
+   :depth: 2
+   :backlinks: top
+
+Requirements
+````````````
+
+Requirements for Ansible are extremely minimal.
+
+Ansible is written for Python 2.6+.  If you are running Python 2.5 on an "Enterprise Linux" variant, we'll show you how to add
+2.6.  Newer versions of Linux and OS X should already have 2.6 or higher.
+
+In additon to Python 2.6+, you will want the following Python modules (installed via pip or perhaps via your OS package manager via slightly different names):
+
+* ``paramiko``
+* ``PyYAML``
+* ``jinja2``
+
+If you are using RHEL or CentOS 5 , python is version 2.4 by default, but you can get python 2.6 installed easily. `Use EPEL <http://fedoraproject.org/wiki/EPEL>`_ and install these dependencies as follows:
+
+.. code-block:: bash
+
+   $ yum install python26 python26-PyYAML python26-paramiko python26-jinja2
+
+
+On the managed nodes, you only need Python 2.4 or later, but if you are are running less than Python 2.6 on them, you will
+also need:
+
+* ``python-simplejson`` 
+
+.. note::
+
+   Ansible's "raw" module (for executing commands in a quick and dirty
+   way) and the script module don't even need that.  So technically, you can use
+   Ansible to install python-simplejson using the raw module, which
+   then allows you to use everything else.  (That's jumping ahead
+   though.)
+
+.. note::
+
+   Python 3 is a slightly different language than Python 2 and most python programs (including
+   Ansible) are not
+   switching over yet.  However, some Linux distributions (Gentoo, Arch) may not have a 
+   Python 2.X interpreter installed by default.  On those systems, you should install one, and set
+   the 'ansible_python_interpreter' variable in inventory to point at your 2.X python.  Distributions
+   like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu all have a 2.X interpreter installed
+   by default and this does not apply to those distributions.  This is also true of nearly all
+   Unix systems.  If you need to bootstrap these remote systems by installing Python 2.X, 
+   using the 'raw' module will be able to do it remotely.
+
+Getting Ansible
+```````````````
+
+If you are interested in using all the latest features, you may wish to keep up to date
+with the development branch of the git checkout.  This also makes it easiest to contribute
+back to the project.  
+
+Instructions for installing from source are below.
+
+Ansible's release cycles are about one month long.  Due to this
+short release cycle, any bugs will generally be fixed in the next release versus maintaining 
+backports on the stable branch.
+
+You may also wish to follow the `Github project <https://github.com/ansible/ansible>`_ if
+you have a github account.  This is also where we keep the issue tracker for sharing
+bugs and feature ideas.
+
+
+Running From Checkout
++++++++++++++++++++++
+
+Ansible is trivially easy to run from a checkout, root permissions are not required
+to use it:
+
+.. code-block:: bash
+
+    $ git clone git://github.com/ansible/ansible.git
+    $ cd ./ansible
+    $ source ./hacking/env-setup
+
+You can optionally specify an inventory file (see :doc:`patterns`) other than /etc/ansible/hosts:
+
+.. code-block:: bash
+
+    $ echo "127.0.0.1" > ~/ansible_hosts
+    $ export ANSIBLE_HOSTS=~/ansible_hosts
+
+You can read more about the inventory file in later parts of the manual.
+
+Now let's test things:
+
+.. code-block:: bash
+
+    $ ansible all -m ping --ask-pass
+
+
+Make Install
+++++++++++++
+
+If you are not working from a distribution where Ansible is packaged yet, you can install Ansible 
+using "make install".  This is done through `python-distutils`:
+
+.. code-block:: bash
+
+    $ git clone git://github.com/ansible/ansible.git
+    $ cd ./ansible
+    $ sudo make install
+
+Via Pip
++++++++
+
+Are you a python developer?
+
+Ansible can be installed via Pip, but when you do so, it will ask to install other dependencies used for
+optional modes::
+
+   $ sudo easy_install pip
+   $ sudo pip install ansible
+
+Readers that use virtualenv can also install Ansible under virtualenv.  Do not use easy_install to install
+ansible directly.
+
+Via RPM
++++++++
+
+RPMs for the last Ansible release are available for `EPEL
+<http://fedoraproject.org/wiki/EPEL>`_ 6 and currently supported
+Fedora distributions.  Ansible itself can manage earlier operating
+systems that contain python 2.4 or higher.
+
+If you are using RHEL or CentOS and have not already done so, `configure EPEL <http://fedoraproject.org/wiki/EPEL>`_
+   
+.. code-block:: bash
+
+    # install the epel-release RPM if needed on CentOS, RHEL, or Scientific Linux
+    $ sudo yum install ansible
+
+You can also use the ``make rpm`` command to build an RPM you can distribute and install. 
+Make sure you have ``rpm-build``, ``make``, and ``python2-devel`` installed.
+
+.. code-block:: bash
+
+    $ git clone git://github.com/ansible/ansible.git
+    $ cd ./ansible
+    $ make rpm
+    $ sudo rpm -Uvh ~/rpmbuild/ansible-*.noarch.rpm
+
+Python 2.6 EPEL instructions for RHEL and CentOS 5
+``````````````````````````````````````````````````
+
+These distributions don't have Python 2.6 by default, but it is easily
+installable. 
+
+
+.. code-block:: bash
+
+
+
+Via MacPorts
+++++++++++++
+
+An OSX port is available via MacPorts, to install the stable version of
+Ansible from MacPorts (this is the recommended way), run:
+
+.. code-block:: bash
+
+    $ sudo port install ansible
+
+If you wish to install the latest build via the MacPorts system from a
+git checkout, run:
+
+.. code-block:: bash
+
+    $ git clone git://github.com/ansible/ansible.git
+    $ cd ./ansible/packaging/macports
+    $ sudo port install
+
+Please refer to the documentation at <http://www.macports.org> for
+further information on using Portfiles with MacPorts.
+
+
+Ubuntu and Debian
++++++++++++++++++
+
+Ubuntu builds are available `in a PPA here <https://launchpad.net/~rquillo/+archive/ansible>`_
+
+Debian/Ubuntu package recipes can also be built from the source checkout, run:
+
+.. code-block:: bash
+
+    $ make debian
+
+Gentoo, Arch, Others
+++++++++++++++++++++
+
+Gentoo eBuilds are in portage, version 1.0 `coming soon <https://bugs.gentoo.org/show_bug.cgi?id=461830>`_.
+
+.. code-block:: bash
+
+    $ emerge ansible
+
+
+An Arch PKGBUILD is available on `AUR <https://aur.archlinux.org/packages.php?ID=58621>`_
+If you have python3 installed on Arch, you probably want to symlink python to python2:
+
+.. code-block:: bash
+
+    $ sudo ln -sf /usr/bin/python2 /usr/bin/python
+
+You should also set a 'ansible_python_interpreter' inventory variable for hosts that have python 
+pointing to python3, so the right python can be found on the managed nodes.
+
+Tagged Releases
++++++++++++++++
+
+Tarballs of releases are available on the ansible.cc page.
+
+* `Ansible/downloads <https://ansible.cc/releases>`_
+
+These releases are also tagged in the git repository with the release version.
+
+Choosing Between Paramiko and Native SSH
+````````````````````````````````````````
+
+By default, ansible uses paramiko to talk to managed nodes over SSH.  Paramiko is fast, works
+very transparently, requires no configuration, and is a good choice for most users.
+However, it does not support some advanced SSH features that folks will want to use.
+
+.. versionadded:: 0.5
+
+If you want to leverage more advanced SSH features (such as Kerberized
+SSH or jump hosts), pass the flag "--connection=ssh" to any ansible
+command, or set the ANSIBLE_TRANSPORT environment variable to
+'ssh'. This will cause Ansible to use openssh tools instead.
+
+If ANSIBLE_SSH_ARGS are not set, ansible will try to use some sensible ControlMaster options
+by default.  You are free to override this environment variable, but should still pass ControlMaster
+options to ensure performance of this transport.  With ControlMaster in use, both transports
+are roughly the same speed.  Without CM, the binary ssh transport is signficantly slower.
+
+If none of this makes sense to you, the default paramiko option is probably fine.
+
+
+Your first commands
+```````````````````
+
+Now that you've installed Ansible, it's time to test it.
+
+Edit (or create) /etc/ansible/hosts and put one or more remote systems in it, for
+which you have your SSH key in ``authorized_keys``::
+
+    192.168.1.50
+    aserver.example.org
+    bserver.example.org
+
+Set up SSH agent to avoid retyping passwords:
+
+.. code-block:: bash
+
+    $ ssh-agent bash
+    $ ssh-add ~/.ssh/id_rsa
+
+(Depending on your setup, you may wish to ansible's --private-key option to specify a pem file instead)
+
+Now ping all your nodes:
+
+.. code-block:: bash
+
+   $ ansible all -m ping
+
+Ansible will attempt to remote connect to the machines using your current
+user name, just like SSH would.  To override the remote user name, just use the '-u' parameter.
+
+If you would like to access sudo mode, there are also flags to do that:
+
+.. code-block:: bash
+
+    # as bruce
+    $ ansible all -m ping -u bruce
+    # as bruce, sudoing to root
+    $ ansible all -m ping -u bruce --sudo 
+    # as bruce, sudoing to batman
+    $ ansible all -m ping -u bruce --sudo --sudo-user batman
+
+(The sudo implementation is changeable in ansbile's configuration file if you happen to want to use a sudo
+replacement.  Flags passed dot sudo can also be set.)
+
+Now run a live command on all of your nodes:
+  
+.. code-block:: bash
+
+   $ ansible all -a "/bin/echo hello"
+
+Congratulations.  You've just contacted your nodes with Ansible.  It's
+now time to read some of the more real-world :doc:`examples`, and explore
+what you can do with different modules, as well as the Ansible
+:doc:`playbooks` language.  Ansible is not just about running commands, it
+also has powerful configuration management and deployment features.  There's more to
+explore, but you already have a fully working infrastructure!
+
+
+.. seealso::
+
+   :doc:`examples`
+       Examples of basic commands
+   :doc:`playbooks`
+       Learning ansible's configuration management language
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+

docsite/rst/glossary.rst

@@ -0,0 +1,430 @@
+Glossary
+========
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+The following is a list (and re-explanation) of term definitions used elsewhere in the Ansible documentation.
+
+Consult the documentation home page for the full documentation and to see this in context, but this should be a good resource
+to check you know all of components of ansible and how they fit together.  It's something you might wish to read for review or
+when a term comes up on the mailing list.
+
+See the main documentation if you are looking for examples to put all of this into context.
+
+Action
+++++++
+
+An action is a part of ref:`task` that says what ref:`module` to run and what arguments to pass to that module.  Each task can
+have only one action, but it may also have other parameters.
+
+Ad Hoc
+++++++
+
+Refers to running ansible to do some quick command, using /usr/bin/ansible, rather than the orchestration language, which is
+/usr/bin/ansible-playbook.  An example of an ad-hoc command might be rebooting 50 machines in your infrastructure.  Anything
+you can do ad-hoc you can do by writing a playbook, and playbooks can also glue lots of other operations together.
+
+Async
++++++
+
+Refers to a task that is configured to run in the background rather than waiting for completion.  If you have a long process
+that would run longer than the SSH timeout, it would make sense to launch that task in async mode.  Async modes can poll
+for completion every so many seconds, or can be configured to "fire and forget" in which case ansible will not even
+check on the task again, it will just kick it off and proceed to future steps.  Async modes work with both /usr/bin/ansible
+and /usr/bin/ansible-playbook.
+
+Callback Plugin
++++++++++++++++
+
+Refers to some user-written code that can intercept the results from Ansbile and do something with it.  Some supplied examples
+in the github project perform custom logging, send email, or even play sound effects.
+
+Check Mode
+++++++++++
+
+Refers to running ansible with --check, which does not make any changes on the remote systems, but only alerts what changes
+might occur if run without --check.  This is analogous to so-called "dry run" mode in other systems, though the user should
+be warned that this does not take into account unexpected command failures or cascade effects (nor do those modes in other
+systems).  Use this to get an idea what might happen, but is not a substitute for a good staging environment.
+
+Connection Type, Connection Plugin
+++++++++++++++++++++++++++++++++++
+
+Ansible by default talks to remote machines over SSH using a library called 'paramiko'.  It also supports using native OpenSSH,
+which if you have a new-enough open SSH, is equally fast, but also enables some features like Kereberos and jump hosts.  This is
+govered in the getting started section.  There are also other connection types like 'fireball' mode, which must be bootstrapped
+over SSH but is very fast, and local mode, which acts on the local system.  Users can also write their own connection plugins.
+
+Conditionals
+++++++++++++
+
+A conditional is an expression that evaluates to true or false that decides whether a given task will be executed on a given
+machine or not.   Ansible's conditionals include 'only_if', and the syntactically superior alternatives 'when_boolean',
+'when_string', and 'when_integer'.  These are discussed in the playbook documentation.
+
+Diff Mode
++++++++++
+
+A --diff flag can be passed to ansible to show how template files change when they are overwritten, or how they might change when used
+with --check mode.   These diffs come out in unified diff format.
+
+Facts
++++++
+
+Facts are simply things that are discovered about remote nodes.  While they can be used in playbooks and templates just like variables, facts
+are things that are inferred, rather than set.  Facts are discovered automatically by ansible when running plays by running the internal 'setup'
+module on the remote nodes.  You never have to call the setup module explicitly, it just runs, but it can be disabled to save time if it is
+not needed.  For convience of users switching from other config systems, the fact module will also pull in facts from the 'ohai' and 'facter'
+tools if they are installed, which are fact libraries from Chef and Puppet, respectfully.
+
+Filter Plugin
++++++++++++++
+
+A filter plugin is something that most users will never need to understand to use at all.  These allow creation of new Jinja2 filters, which
+are more of less only of use to people who know what Jinja2 filters are.  If you need them, you can learn how to write them in the API
+docs section.
+
+Fireball Mode
++++++++++++++
+
+By default Ansible uses SSH for connections -- either Paramiko (the actual default) or a common alternative, native Open SSH.  Some users
+may want to execute operations even faster though, and they can if they opt in on running an ephmeral message bus.  What happens is Ansible
+will start talking to a node over SSH, and then set up a temporary secured message bus good only to talk from one machine, that will
+self destruct after a set period of time.  This means the bus does not allow management of any kind after the time interval has expired.
+
+Forks
++++++
+
+Ansible talks to remote nodes in parallel, the level of parallelism can be set either by passing --forks, or editing the default in a configuration
+file.  The default is a very conservative 5 forks, though if you have a lot of RAM, you can easily set this to a value like 50 for increased
+parallelism.  
+
+Gather Facts (Boolean)
+++++++++++++++++++++++
+
+Facts are mentioned above.  Sometimes in running a multi-play playbook it is deseriable to have some plays that don't bother with fact
+computation as they aren't going to need any values from facts.  Setting `gather_facts: False` on a playbook allows this implicit
+fact gathering to be skipped.
+
+Globbing
+++++++++
+
+Globbing is a way to select lots of hosts based on wildcard, rather than the name of the host specifically, or the name of the group
+they are in.  For instance, it is possible to select "www*" to match all hosts starting with "www".   This concept is pulled directly
+from Func, one of Michael's earlier projects.  In addition to basic globbing, various set operations are also possible, such as
+hosts in this group and not in another group, and so on.
+
+Group
++++++
+
+A group consists of several hosts assigned to a pool that can be targetted conviently together, and also given variables that they share in
+common.
+
+Group Vars
+++++++++++
+
+The "group_vars/" files are files that live in a directory alongside an inventory file, with an optional filename named after each group.
+This is a convient place to put variables that will be provided to a given group, especially complex datastructures, so that these
+variables do not have to be embedded in the inventory file or playbook.
+
+Handlers
+++++++++
+
+Handlers are just like regular tasks in an ansible playbok (see Tasks), but are only run if the Task contains a "notify" directive and
+also indicates that it changed something.  An example is if a config file is changed, the task referencing the config file templating
+operation may notify a service restart handler when it changes.  This means services can be bounced only if they need to be restarted.
+Handlers can be used for things other than service restarts, but service restarts are the most common usage.
+
+Host
+++++
+
+A host is simply a remote machine that ansible manages.  They can have individual variables assigned to them, and can also be organized
+in groups.  All hosts have a name they can be reached at (which is either an IP address or a domain name) and optionally a port number,
+if they are not to be accessed on the default SSH port.
+
+Host Specifier
+++++++++++++++
+
+Each Play in Ansbile maps a series of tasks (which define the role, purpose, or orders of a system) to a set of systems.
+
+This "hosts:" directive in each play is often called the hosts specifier.
+
+It may select one system, many systems, one or more groups, or even some hosts that in one group and explicitly not in another.
+
+Host Vars
++++++++++
+
+Just like "Group Vars", a directory alongside the inventory file named "host_vars/" can contain a file named after each hostname in
+the inventory file, in YAML format.  This provides a convient place to assign variables to the host without having to embed
+them in the inventory file.  The Host Vars file can also be used to define complex datastructures that can't be represented in the
+inventory file.
+
+Lazy Evalution
+++++++++++++++
+
+In general Ansible evaluates any variables in playbook content at the last possible second, which means that if you define a datastructure
+that datastructure itself can define variable values within it, and everything "just works" as you would expect.  This also means variable
+strings can include other variables inside of those strings.
+
+Lookup Plugin
++++++++++++++
+
+A lookup plugin is a way to get data into Ansible from the outside world.  These are how such things as "with_items" are implemented, which is a
+basic looping plugin, but there are also things like "with_file" which loads data from a file, and even things for querying environment variables,
+DNS text records, or key value stores.  Lookup plugins can also be accessed in templates using an all caps form, such as the contents of a file
+on the local machine can be accessed like ``$FILE(/path/to/file)``.
+
+Multi-Tier
+++++++++++
+
+The concept that IT systems are not managed one system at a time, but by interactions between multiple systems, and groups of systems, in
+well defined orders.  For instance, a web server may need to be updated before a database server, and pieces on the web server may need
+to be updated after *THAT* database server, and various load balancers and monitoring servers may need to be contacted.  Ansible models
+entire IT topologies and workflows rather than looking at configuration in a "one system at a time" perspective.
+
+Idempotency
++++++++++++
+
+The concept that change commands should only be applied when they need to be applied, and that it is better to describe the desired
+state of a system than the process of how to get to that state.  As an analogy, the path from North Carolina in the United States to
+California involves driving a very long way West, but if I were instead in Anchorage, Alaska, driving a long ways west is no longer
+the right way to get to California.  Ansible's Resources like you to say "put me in California" and then decide how to get there.  If
+you were already in California, nothing needs to happen, and it will let you know it didn't need to change anything.
+
+Includes
+++++++++
+
+The idea that playbook files (which are nothing more than list of plays) can include other lists of plays, and task lists
+can externalize lists of tasks in other files, and similarly with handlers.  Includes can be parameterized, which means that the
+loaded file can pass variables.  For instance, an included play for setting up a wordpress blog may take a parameter called "user"
+and thant play could be included more than once to create a blog for both "alice" and "bob".
+
+Inventory
++++++++++
+
+A file (by default, Ansible uses a simple INI format) that describes Hosts and Groups in Ansible.  Inventory can also be provided
+via an "Inventory Script" (sometimes called an "External Inventory Script").  
+
+Inventory Script
+++++++++++++++++
+
+A very simple program (or a complicated one) that looks up hosts, group membership for hosts, and variable information from an external
+resource -- whether that be a SQL database, a CMDB solution, or something like LDAP.  This concept was adapted from Puppet (where it is
+called an "External Nodes Classifier") and works more or less exactly the same way.
+
+Jinja2
+++++++
+
+Jinja2 is the preferred templating language of Ansbile's template module.  It is a very simple Python template language that is generally
+readable and easy to write.
+
+JSON
+++++
+
+Ansible uses JSON for return data from remote modules.  This allows modules to be written in any language, not just Python.
+
+only_if
++++++++
+
+A conditional statement that decides if a task is going to be executed in a playbook based on whether if the following expression
+given is true or false.  The newer 'when_' statements provide a cleaner way to express conditionals, 'only_if' is an older
+construct.  Though it may be still be useful in advanced situations.
+
+Library
++++++++
+
+A collection of modules made availabe to /usr/bin/ansible or an ansible playbook.
+
+Limit Groups
+++++++++++++
+
+By passing "--limit somegroup" to ansible or ansible playbook, the commands can be limited to a subset of hosts.  For instance, 
+this can be used to run a playbook that normally targets an entire set of servers to one particular server.
+
+Local Connection
+++++++++++++++++
+
+By using "connection: local" in a playbook, or "-c local" to /usr/bin/ansible, this indicates that we are managing the local
+host and not a remote machine.
+
+Local Action
+++++++++++++
+
+A local_action directive in a playbook targetting remote machines means that the given step will actually occur on local
+machine, but that the variable '$ansible_hostname' can be passed in to reference the remote hostname being referred to in
+that step.  This can be used to trigger, for example, an rsync operation.
+
+Loops
++++++
+
+Generally Ansible is not a programming language, it prefers to be more declarative, though various constructs like "with_items"
+allow a particular task to be repeated for multiple items in a list.  Certain modules, like yum and apt, are actually optimized
+for this, and can install all packages given in those lists within a single transaction, dramatically speaking up total
+time to configuration.
+
+Modules
++++++++
+
+Modules are the units of work that Ansible ships out to remote machines.   Modules are kicked off by either /usr/bin/ansible or
+/usr/bin/ansible-playbook (where multiple tasks use lots of different modules in conjunction).  Modules can be implemented in any
+language including Perl, Bash, or Ruby -- but can leverage some useful communal library code if written in Python.  Modules just
+have to return JSON or simple key=value pairs.  Once modules are executed on remote machines, they are removed, so no long running
+daemons are used.  Ansible refers to the collection of available modules as a 'library'.
+
+Notify
+++++++
+
+The act of a task registering a change event and informing a handler task that another action needs to be run at the end of the play.
+If a handler is notified by multiple tasks, it will still be run only once.  Handlers are run in the order they are listed, not
+in the order that they are notified.
+
+Orchestration
++++++++++++++
+
+Many software automation systems use this word to mean different things.  Ansible uses it as a conductor would conduct an orchestra.
+A datacenter or cloud architecture is full of many systems, playing many parts -- web servers, database servers, maybe load balancers,
+monitoring systems, continuous integration systems, etc.  In performing any process, it is neccessary to touch systems in particular orders,
+often to simulate rolling updates or deploy software correctly.  Some system may perform some steps, then others, then previous systems
+already processed may need to perform more steps.  Along the way, email may need to be sent or web services contacted.  Ansible
+orchestration is all about modelling that kind of process.
+
+Paramiko
+++++++++
+
+Ansible by default manages machines over SSH.   The library that ansible uses by default to do this is a python-powered library called
+Paramiko.  Paramiko is generally fast and easy to manage, though users desiring Kerberos or Jump Host support may wish to switch
+to the native SSH connection type, by specifying the connection type in their playbook or using the "-c ssh" flag.
+
+Playbooks
++++++++++
+
+Playbooks are the language by which Ansible orchestrates, configures, administers, or deploys systems.  They are called playbooks partially because it's a sports analogy, and it's supposed to be fun using them.  They aren't workbooks :)
+
+Plays
++++++
+
+A playbook is a list of plays.  A play is minimally a mapping between a set of hosts (usually chosen by groups, but sometimes my hostname
+globs), selected by a host specifier -- and the tasks which run on those hosts to define the role at which those systems will perform. There
+can be one or many plays in a playbook.
+
+Pull Mode
++++++++++
+
+Ansible by default runs in push mode, which allows it very fine grained control over when it talks to what kinds of systems.  Pull mode is
+provided for when you would rather have nodes check in every N minutes on a particular schedule.  It uses a program called ansible-pull and can also be set up (or reconfigured) using a push-mode playbook.  Most ansible users use push mode, but it is included for variety and the sake
+of having choices.
+
+ansible-pull works by checking configuration orders out of git on a crontab and then managing the machine locally, using the local
+connection plugin.
+
+Push Mode
++++++++++
+
+Push mode is the default mode of ansible, in fact, it's not really a mode at all -- it's just how ansible works when you aren't
+thinking about it.  Push mode allows ansible to be fine grained and conduct nodes in complex orchestration processes without
+waiting for them to check in.
+
+Register Variable
++++++++++++++++++
+
+The result of running any task in ansible can be stored in a variable for use in a template or a conditional statement.
+The keyword used to name the variable to use is called 'register', taking it's name from the idea of registers in assembly
+programming, though Ansible will never feel like assembly programming.  There are an infinite number of variable names
+you can use for registration.
+
+Resource Model
+++++++++++++++
+
+Ansible modules work in terms of resources.   For instance the file module will select a particular file, say, /etc/motd
+and ensure that attributes of that resource match a particular model, for instance, we might wish to set the ownership
+to 'root' if not already set to root, or set the mode to '0644' if not already set to '0644'.  The resource models
+are 'idempotent' meaning change commands are not run unless needed, and ansible will bring the system back to a desired
+state regardless of the actual state -- rather than you having to tell it how to get to the state.
+
+Rolling Update
+++++++++++++++
+
+The act of addressing a number of nodes in a group N at a time to avoid updating them all at once and bringing the system
+offline.  For instance, in a web topology of 500 nodes handling very large volume, it may be reasonable to update 10 or 20
+machines at a time, moving on to the next 10 or 20 when done.  The "serial:" keyword in an ansible playbook controls the
+size of the rolling update pool.  The default is to address the batch size all at once, so this is something that you must
+opt-in to.  OS configuration (such as making sure config files are correct) does not typically have to use the rolling update
+model, but can if desired.
+
+Runner
+++++++
+
+A core software component of ansible that is the power behind /usr/bin/ansible directly -- and corresponds to the invocation
+of each task in a playbook.  The Runner is something ansible developers may talk about, but it's not really userland
+vocabulary.
+
+Serial
+++++++
+
+See "Rolling Update".
+
+Sudo
+++++
+
+Ansible does not require root logins, and since it's daemonless, definitely does not require root level daemons (which can
+be a security concern in sensitive environments).  Ansible can log in and perform many operations wrapped in a sudo command,
+and can work with both passwordless and passworded sudo.  Some operations that don't normally work with sudo (like scp
+file transfer) can be achieved with Ansible's copy, template, and fetch resources while running in sudo mode.
+
+SSH (Native)
+++++++++++++
+
+Ansible by default uses Paramiko.  Native openssh is specified with "-c ssh" (or a config file, or a directive in the playbook)
+and can be useful if wanting to login via Kerberized SSH or use SSH jump hosts, etc.  Using a client that supports ControlMaster
+and ControlPersist is recommended for maximum performance -- if you don't have that and don't need Kerberos, jump hosts, or other
+features, paramiko (the default) is a fine choice.  Ansible will warn you if it doesn't detect ControlMaster/ControlPersist capability.
+
+Tags
+++++
+
+Ansbile allows tagging resources in a playbook with arbitrary keywords, and then running only the parts of the playbook that
+correspond to those certain keywords.  For instance, it is possible to have an entire OS configuration, and have certain steps
+labelled "ntp", and then run just the "ntp" steps to reconfigure the time server information on a remote server.
+
+Tasks
++++++
+
+Playbooks exist to run tasks.  Tasks combine an action (a module combined with what variables to pass) with a name and optionally some other keywords (like looping directives).   Handlers are also Tasks, but they are a special kind of task that do not run unless they are notified by name when a task reports an underlying change on a remote system.
+
+Templates
++++++++++
+
+Ansible can easily transfer remote files to remote systems, but often it is desirable to substitute variables in other files.  Variables
+may come from the inventory file, Host Vars, Group Vars, or Facts -- templates use the Jinja2 template engine and can also include logical
+constructs like loops and if statements.
+
+Transport
++++++++++
+
+Ansible uses "Connection Plugins" to define types of available transports.  These are simply how ansible will reach out to managed systems.  Transports included are paramiko (the default SSH transport), SSH (using openssh), fireball (an SSH bootstrapped accelerated connection plugin), and local. 
+
+When
+++++
+
+When statements (when_string, when_changed, when_boolean, when_integer, etc) are easier to write forms of the only_if conditional. They can be affixed to any task to make that task decide to run only when an expression involving variables or facts is actually true.
+
+Van Halen
++++++++++
+
+For no particular reason other than Michael really likes them, all Ansible releases are code named after Van Halen songs.  There is no preference given to David Lee Roth vs Sammy Lee Hagar era songs, and instrumentals are also allowed.  It is unlikely there will never be a Jump release, but it may be there is going to be a Van Halen III codenamed release.  You never know.
+
+Vars (Variables)
+++++++++++++++++
+
+As opposed to Facts, variables are names of values (they can be simple scalar values --integers, booleans, strings) or complex ones (dictionaries/hashes, lists) that can be used in templates and playbooks.  They are declared things, not things that are inferred from the remote systems current state or nature (which is what Facts are).
+
+YAML
+++++
+
+Ansible does not want to force people to write programming language code to automate infrastructure, so Ansible uses YAML to define playbook configuration languages and also variable files.  YAML is nice because it has a minimum of syntax and is very clean and easy for people to skim.  It is a good data format for configuration files and humans, but also machine readable.  Ansible's usage of YAML stemmed from Michael's first use of it inside of Cobbler around 2006.  YAML is fairly popular in the dynamic language community and the format has libraries available
+for serialization in many different languages (Python, Perl, Ruby, etc).
+
+

docsite/rst/index.rst

@@ -0,0 +1,83 @@
+
+
+Ansible Documentation
+`````````````````````
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+This page contains documentation about how to use `Ansible <http://ansible.cc>`_.  You may also be interested in taking a class:
+
+.. image:: http://www.ansibleworks.com.s3-website-us-east-1.amazonaws.com/img/banners/training.png
+   :alt: ansibleworks training
+   :target: http://www.ansibleworks.com/training/
+
+Before we dive into playbooks, configuration management, deployment, and orchestration, we'll learn how to get Ansible installed and some
+basic information.  We'll go over how to execute ad-hoc commands in parallel across your nodes using /usr/bin/ansible.  We'll also see 
+what sort of modules are available in Ansible's core (though you can also write your own, which we'll also show later).
+
+
+.. toctree::
+   :maxdepth: 1
+
+   gettingstarted
+   patterns
+   examples
+   modules
+
+Overview
+````````
+
+.. image:: http://ansible.cc/img/ansible_arch.png
+   :alt: ansible architecture diagram  
+   :width: 566px
+   :height: 439px
+
+
+Playbooks
+`````````
+
+Playbooks are Ansible's orchestration language.  At a basic level, playbooks can be used to manage configurations and deployments
+of remote machines.  At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions
+to other hosts, interacting with monitoring servers and load balancers along the way.  You can start small and pick up more features 
+over time as you need them.  Playbooks are designed to be human-readable and are developed in a basic text language.  There are multiple
+ways to organize playbooks and the files they include, and we'll offer up some suggestions on that and making the most out of Ansible.
+
+.. toctree::
+   :maxdepth: 1
+
+   playbooks
+   playbooks2
+   bestpractices
+   YAMLSyntax
+   Example Playbooks <https://github.com/ansible/ansible-examples>
+
+Developer Information
+`````````````````````
+
+Learn how to build modules of your own in any language.   Explore Ansible's Python API and write Python plugins to integrate
+with other solutions in your environment.
+
+.. toctree::
+   :maxdepth: 1
+
+   api
+   moduledev
+
+Miscellaneous
+`````````````
+
+`Learn and share neat Ansible tricks on Coderwall <https://coderwall.com/p/t/ansible>`_ - sign-in using GitHub or Twitter to vote on top tips and add your own!
+
+`A list of some Ansible users and quotes about Ansible <http://www.ansibleworks.com/users>`_.
+
+More links:
+
+.. toctree::
+   :maxdepth: 1
+
+   contrib
+   glossary
+

docsite/rst/moduledev.rst

@@ -0,0 +1,455 @@
+Module Development
+==================
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+Ansible modules are reusable units of magic that can be used by the Ansible API,
+or by the `ansible` or `ansible-playbook` programs.
+
+Modules can be written in any language and are found in the path specified
+by `ANSIBLE_LIBRARY` or the ``--module-path`` command line option.
+
+.. contents::
+   :depth: 2
+   :backlinks: top
+
+
+Tutorial
+````````
+Let's build a module to get and set the system time.  For starters, let's build
+a module that just outputs the current time.
+
+We are going to use Python here but any language is possible.  Only File I/O and outputing to standard
+out are required.  So, bash, C++, clojure, Python, Ruby, whatever you want
+is fine.
+
+Now Python Ansible modules contain some extremely powerful shortcuts (that all the core modules use)
+but first we are going to build a module the very hard way.  The reason we do this is because modules
+written in any language OTHER than Python are going to have to do exactly this.  We'll show the easy
+way later.
+
+So, here's an example.  You would never really need to build a module to set the system time,
+the 'command' module could already be used to do this.  Though we're going to make one.
+
+Reading the modules that come with ansible (linked above) is a great way to learn how to write
+modules.   Keep in mind, though, that some modules in ansible's source tree are internalisms,
+so look at `service` or `yum`, and don't stare too close into things like `async_wrapper` or
+you'll turn to stone.  Nobody ever executes async_wrapper directly.
+
+Ok, let's get going with an example.  We'll use Python.  For starters, save this as a file named `time`::
+
+    #!/usr/bin/python
+
+    import datetime
+    import json
+
+    date = str(datetime.datetime.now())
+    print json.dumps({
+        "time" : date
+    })
+
+Testing Modules
+```````````````
+
+There's a useful test script in the source checkout for ansible::
+
+    git clone git@github.com:ansible/ansible.git
+    chmod +x ansible/hacking/test-module
+
+Let's run the script you just wrote with that::
+
+    ansible/hacking/test-module -m ./time
+
+You should see output that looks something like this::
+
+    {u'time': u'2012-03-14 22:13:48.539183'}
+
+If you did not, you might have a typo in your module, so recheck it and try again.
+
+Reading Input
+`````````````
+
+Let's modify the module to allow setting the current time.  We'll do this by seeing
+if a key value pair in the form `time=<string>` is passed in to the module.
+
+Ansible internally saves arguments to an arguments file.  So we must read the file
+and parse it.  The arguments file is just a string, so any form of arguments are legal.
+Here we'll do some basic parsing to treat the input as key=value.
+
+The example usage we are trying to achieve to set the time is::
+
+   time time="March 14 22:10"
+
+If no time parameter is set, we'll just leave the time as is and return the current time.
+
+.. note:
+   This is obviously an unrealistic idea for a module.  You'd most likely just
+   use the shell module.  However, it probably makes a decent tutorial.
+
+Let's look at the code.  Read the comments as we'll explain as we go.  Note that this
+is highly verbose because it's intended as an educational example.  You can write modules
+a lot shorter than this::
+
+    #!/usr/bin/python
+
+    # import some python modules that we'll use.  These are all
+    # available in Python's core
+
+    import datetime
+    import sys
+    import json
+    import os
+    import shlex
+
+    # read the argument string from the arguments file
+    args_file = sys.argv[1]
+    args_data = file(args_file).read()
+
+    # for this module, we're going to do key=value style arguments
+    # this is up to each module to decide what it wants, but all
+    # core modules besides 'command' and 'shell' take key=value
+    # so this is highly recommended
+
+    arguments = shlex.split(args_data)
+    for arg in arguments:
+
+        # ignore any arguments without an equals in it
+        if arg.find("=") != -1:
+
+            (key, value) = arg.split("=")
+
+            # if setting the time, the key 'time'
+            # will contain the value we want to set the time to
+
+            if key == "time":
+
+                # now we'll affect the change.  Many modules
+                # will strive to be 'idempotent', meaning they
+                # will only make changes when the desired state
+                # expressed to the module does not match
+                # the current state.  Look at 'service'
+                # or 'yum' in the main git tree for an example
+                # of how that might look.
+
+                rc = os.system("date -s \"%s\"" % value)
+
+                # always handle all possible errors
+                #
+                # when returning a failure, include 'failed'
+                # in the return data, and explain the failure
+                # in 'msg'.  Both of these conventions are
+                # required however additional keys and values
+                # can be added.
+
+                if rc != 0:
+                    print json.dumps({
+                        "failed" : True,
+                        "msg"    : "failed setting the time"
+                    })
+                    sys.exit(1)
+
+                # when things do not fail, we do not
+                # have any restrictions on what kinds of
+                # data are returned, but it's always a
+                # good idea to include whether or not
+                # a change was made, as that will allow
+                # notifiers to be used in playbooks.
+
+                date = str(datetime.datetime.now())
+                print json.dumps({
+                    "time" : date,
+                    "changed" : True
+                })
+                sys.exit(0)
+
+    # if no parameters are sent, the module may or
+    # may not error out, this one will just
+    # return the time
+
+    date = str(datetime.datetime.now())
+    print json.dumps({
+        "time" : date
+    })
+
+Let's test that module::
+
+    ansible/hacking/test-module -m ./time -a time=\"March 14 12:23\"
+
+This should return something like::
+
+    {"changed": True, "time": "2012-03-14 12:23:00.000307"}
+
+Module Provided 'Facts'
+```````````````````````
+
+The 'setup' module that ships with Ansible provides many variables about a system that can be used in playbooks
+and templates.  However, it's possible to also add your own facts without modifying the system module.  To do
+this, just have the module return a `ansible_facts` key, like so, along with other return data::
+
+    {
+        "changed" : True,
+        "rc" : 5,
+        "ansible_facts" : {
+            "leptons" : 5000
+            "colors" : {
+                "red"   : "FF0000",
+                "white" : "FFFFFF"
+            }
+        }
+    }
+
+These 'facts' will be available to all statements called after that module (but not before) in the playbook.
+A good idea might be make a module called 'site_facts' and always call it at the top of each playbook, though
+we're always open to improving the selection of core facts in Ansible as well.
+
+Common Module Boilerplate
+`````````````````````````
+
+As mentioned, if you are writing a module in Python, there are some very powerful shortcuts you can use.
+Modules are still transferred as one file, but an arguments file is no longer needed, so these are not
+only shorter in terms of code, they are actually FASTER in terms of execution time.
+
+Rather than mention these here, the best way to learn is to read some of the `source of the modules <https://github.com/ansible/ansible/tree/devel/library>`_ that come with Ansible.
+
+The 'group' and 'user' modules are reasonably non-trival and showcase what this looks like.
+
+Key parts include always ending the module file with::
+
+    # include magic from lib/ansible/module_common.py
+    #<<INCLUDE_ANSIBLE_MODULE_COMMON>>
+    main()
+
+And instantiating the module class like::
+
+    module = AnsibleModule(
+        argument_spec = dict(
+            state     = dict(default='present', choices=['present', 'absent']),
+            name      = dict(required=True),
+            enabled   = dict(required=True, choices=BOOLEANS),
+            something = dict(aliases=['whatever'])
+        )
+    )
+
+The AnsibleModule provides lots of common code for handling returns, parses your arguments
+for you, and allows you to check inputs.
+
+Successful returns are made like this::
+
+    module.exit_json(changed=True, something_else=12345)
+
+And failures are just as simple (where 'msg' is a required parameter to explain the error)::
+
+    module.fail_json(msg="Something fatal happened")
+
+There are also other useful functions in the module class, such as module.md5(path).  See
+lib/ansible/module_common.py in the source checkout for implementation details.
+
+Again, modules developed this way are best tested with the hacking/test-module script in the git
+source checkout.  Because of the magic involved, this is really the only way the scripts
+can function outside of Ansible.
+
+If submitting a module to ansible's core code, which we encourage, use of the AnsibleModule
+class is required.
+
+Check Mode
+``````````
+.. versionadded:: 1.1
+
+Modules may optionally support check mode. If the user runs Ansible in check
+mode, the module should try to predict whether changes will occur.
+
+For your module to support check mode, you must pass ``supports_check_mode=True``
+when instantiating the AnsibleModule object. The AnsibleModule.check_mode attribute
+will evaluate to True when check mode is enabled. For example::
+
+    module = AnsibleModule(
+        argument_spec = dict(...),
+        supports_check_mode=True
+    )
+
+    if module.check_mode:
+        # Check if any changes would be made by don't actually make those changes
+        module.exit_json(changed=check_if_system_state_would_be_changed())
+
+Remember that, as module developer, you are responsible for ensuring that no
+system state is altered when the user enables check mode.
+
+If your module does not support check mode, when the user runs Ansible in check
+mode, your module will simply be skipped.
+
+Common Pitfalls
+```````````````
+
+You should also never do this in a module::
+
+    print "some status message"
+
+Because the output is supposed to be valid JSON.  Except that's not quite true,
+but we'll get to that later.
+
+Modules must not output anything on standard error, because the system will merge
+standard out with standard error and prevent the JSON from parsing. Capturing standard
+error and returning it as a variable in the JSON on standard out is fine, and is, in fact,
+how the command module is implemented.
+
+If a module returns stderr or otherwise fails to produce valid JSON, the actual output
+will still be shown in Ansible, but the command will not succeed.
+
+Always use the hacking/test-module script when developing modules and it will warn
+you about these kind of things.
+
+Conventions/Recommendations
+```````````````````````````
+
+As a reminder from the example code above, here are some basic conventions
+and guidelines:
+
+* If the module is addressing an object, the parameter for that object should be called 'name' whenever possible, or accept 'name' as an alias.
+
+* If you have a company module that returns facts specific to your installations, a good name for this module is `site_facts`.
+
+* Modules accepting boolean status should generally accept 'yes', 'no', 'true', 'false', or anything else a user may likely throw at them.  The AnsibleModule common code supports this with "choices=BOOLEANS" and a module.boolean(value) casting function.
+
+* Include a minimum of dependencies if possible.  If there are dependencies, document them at the top of the module file, and have the module raise JSON error messages when the import fails.
+
+* Modules must be self contained in one file to be auto-transferred by ansible.
+
+* If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible.  This is entirely optional and up to you.
+
+* Modules should return JSON or key=value results all on one line.  JSON is best if you can do JSON.  All return types must be hashes (dictionaries) although they can be nested.  Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary.
+
+* In the event of failure, a key of 'failed' should be included, along with a string explanation in 'msg'.  Modules that raise tracebacks (stacktraces) are generally considered 'poor' modules, though Ansible can deal with these returns and will automatically convert anything unparseable into a failed result.  If you are using the AnsibleModule common Python code, the 'failed' element will be included for you automatically when you call 'fail_json'.
+
+* Return codes from modules are not actually not signficant, but continue on with 0=success and non-zero=failure for reasons of future proofing.
+
+* As results from many hosts will be aggregrated at once, modules should return only relevant output.  Returning the entire contents of a log file is generally bad form.
+
+Shorthand Vs JSON
+`````````````````
+
+To make it easier to write modules in bash and in cases where a JSON
+module might not be available, it is acceptable for a module to return
+key=value output all on one line, like this.   The Ansible parser
+will know what to do::
+
+    somekey=1 somevalue=2 rc=3 favcolor=red
+
+If you're writing a module in Python or Ruby or whatever, though, returning
+JSON is probably the simplest way to go.
+
+
+Documenting Your Module
+```````````````````````
+
+All modules included in the CORE distribution must have a
+``DOCUMENTATION`` string. This string MUST be a valid YAML document
+which conforms to the schema defined below. You may find it easier to
+start writing your ``DOCUMENTATION`` string in an editor with YAML
+syntax highlighting before you include it in your Python file.
+
+Example
++++++++
+
+Here's a correctly formatted YAML document we could use for a
+``DOCUMENTATION`` string:
+
+.. literalinclude:: ../../examples/DOCUMENTATION.yaml
+
+This is available in the 'examples/' directory of the of the Ansible
+github repository, and you can have that generated with
+``./hacking/module_formatter.py -G``. You can copy it into your module and use
+it as a starting point when writing your own docs.
+
+Include it in your module file like this::
+
+    #!/usr/bin/env python
+    # Copyright header....
+
+    DOCUMENTATION = '''
+    ---
+    module: modulename
+    short_description: This is a sentence describing the module
+    # ... snip ...
+    examples:
+        - code: modulename opt1=arg1 opt2=arg2
+          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)``.
+
+Examples (which typically contain colons, quotes, etc.) are difficult
+to format with YAML, so these can (alternatively, or additionally) be
+written in plain text in an ``EXAMPLES`` string within the module
+like this::
+
+    EXAMPLES = '''
+    - action: modulename opt1=arg1 opt2=arg2
+    '''
+
+The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
+``EXAMPLES`` blob after any existing ``examples`` you may have in the
+YAML ``DOCUMENTATION`` string.
+
+Building & Testing
+++++++++++++++++++
+
+Put your completed module file into the 'library' directory and then
+run the command: ``make webdocs``. The new 'modules.html' file will be
+built and appear in the 'docsite/' directory.
+
+You can also test-build your docs one-by-one using the
+``module_formatter.py`` script:
+
+.. code-block:: bash
+
+   $ ./hacking/module_formatter.py -t man -M library/ -m git > ansible-git.1
+   $ man ./ansible-git.1
+
+This will build a manpage for the git module, and look in the
+'library/' directory for the module source. To see all the other
+output formats available:
+
+.. code-block:: bash
+
+   $ ./hacking/module_formatter.py -t --help
+
+
+.. tip::
+
+   If you're having a problem with the syntax of your YAML you can
+   validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
+
+.. tip::
+
+    You can use ANSIBLE_KEEP_REMOTE_FILES=1 to prevent ansible from
+    deleting the remote files so you can debug your module.
+
+Getting Your Module Into Core
+`````````````````````````````
+
+High-quality modules with minimal dependencies
+can be included in the core, but core modules (just due to the programming
+preferences of the developers) will need to be implemented in Python and use
+the AnsibleModule common code, and should generally use consistent arguments with the rest of
+the program.   Stop by the mailing list to inquire about requirements.
+
+.. seealso::
+
+   :doc:`modules`
+       Learn about available modules
+   `Ansible Resources <https://github.com/ansible/ansible/tree/devel/contrib>`_
+       User contributed playbooks, modules, and articles
+   `Github modules directory <https://github.com/ansible/ansible/tree/devel/library>`_
+       Browse source of core modules
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel

docsite/rst/modules.rst

@@ -0,0 +1,85 @@
+Ansible Modules
+===============
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+.. contents::
+   :depth: 2
+   :backlinks: top
+
+Introduction
+````````````
+
+
+Ansible ships with a number of modules (called the 'module library')
+that can be executed directly on remote hosts or through :doc:`playbooks`.
+Users can also write their own modules.   These modules can control system
+resources, like services, packages, or files (anything really), or
+handle executing system commands.
+
+Let's review how we execute three different modules from the command line::
+
+    ansible webservers -m service -a "name=httpd state=running"
+    ansible webservers -m ping
+    ansible webservers -m command -a "/sbin/reboot -t now"
+
+Each module supports taking arguments.  Nearly all modules take ``key=value``
+arguments, space delimited.  Some modules take no arguments, and the
+command/shell modules simply take the string of the command you want to run.
+
+From playbooks, Ansible modules are executed in a very similar way::
+
+    - name: reboot the servers
+      action: command /sbin/reboot -t now
+
+Version 0.8 and higher support the following shorter syntax::
+
+    - name: reboot the servers
+      command: /sbin/reboot -t now
+
+All modules technically return JSON format data, though if you are using the
+command line or playbooks, you don't really need to know much about
+that.  If you're writing your own module, you care, and this means you do
+not have to write modules in any particular language -- you get to choose.
+
+Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made.  When using Ansible
+playbooks, these modules can trigger 'change events' in the form of notifying 'handlers'
+to run additional tasks.
+
+Documention for each module can be accessed from the command line with the
+ansible-doc as well as the man command::
+
+    ansible-doc command
+
+    man ansible.template
+
+Let's see what's available in the Ansible module library, out of the box:
+
+
+.. include:: modules/_list.rst
+
+
+Writing your own modules
+````````````````````````
+
+See :doc:`moduledev`.
+
+.. seealso::
+
+   :doc:`contrib`
+       User contributed playbooks, modules, and articles
+   :doc:`examples`
+       Examples of using modules in /usr/bin/ansible
+   :doc:`playbooks`
+       Examples of using modules with /usr/bin/ansible-playbook
+   :doc:`moduledev`
+       How to write your own modules
+   :doc:`api`
+       Examples of using modules with the Python API
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+

docsite/rst/patterns.rst

@@ -0,0 +1,244 @@
+.. _patterns:
+
+Inventory & Patterns
+====================
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+Ansible works against multiple systems in your infrastructure at the
+same time.  It does this by selecting portions of systems listed in
+Ansible's inventory file, which defaults to /etc/ansible/hosts.
+
+.. contents:: `Table of contents`
+   :depth: 2
+   :backlinks: top
+
+.. _inventoryformat:
+
+Hosts and Groups
+++++++++++++++++
+
+The format for /etc/ansible/hosts is an INI format and looks like this::
+
+    mail.example.com
+
+    [webservers]
+    foo.example.com
+    bar.example.com
+
+    [dbservers]
+    one.example.com
+    two.example.com
+    three.example.com
+
+The things in brackets are group names. You don't have to have them,
+but they are useful.
+
+If you have hosts that run on non-standard SSH ports you can put the port number
+after the hostname with a colon.  Ports listed in any SSH config file won't be read,
+so it is important that you set them if things are not running on the default port::
+
+    badwolf.example.com:5309
+
+Suppose you have just static IPs and want to set up some aliases that don't live in your host file, or you are connecting through tunnels.  You can do things like this::
+
+    jumper ansible_ssh_port=5555 ansible_ssh_host=192.168.1.50
+
+In the above example, trying to ansible against the host alias "jumper" (which may not even be a real hostname) will contact 192.168.1.50 on port 5555.
+
+Adding a lot of hosts?  In 0.6 and later, if you have a lot of hosts following similar patterns you can do this rather than listing each hostname::
+
+    [webservers]
+    www[01:50].example.com
+
+
+In 1.0 and later, you can also do this for alphabetic ranges::
+
+    [databases]
+    db-[a:f].example.com
+
+For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive.
+
+In 1.1 and later, you can also select the connection type and user on a per host basis::
+
+   [targets]
+
+   localhost              ansible_connection=local
+   other1.example.com     ansible_connection=ssh        ansible_ssh_user=mpdehaan
+   other2.example.com     ansible_connection=ssh        ansible_ssh_user=mdehaan
+
+All of these variables can of course also be set outside of the inventory file, in 'host_vars' if you wish
+to keep your inventory file simple.
+
+Selecting Targets
++++++++++++++++++
+
+We'll go over how to use the command line in :doc:`examples` section, however, basically it looks like this::
+
+    ansible <pattern_goes_here> -m <module_name> -a <arguments>
+
+Such as::
+
+    ansible webservers -m service -a "name=httpd state=restarted"
+
+Within :doc:`playbooks`, these patterns can be used for even greater purposes.
+
+Anyway, to use Ansible, you'll first need to know how to tell Ansible which hosts in your inventory file to talk to.
+This is done by designating particular host names or groups of hosts.
+
+The following patterns target all hosts in the inventory file::
+
+    all
+    *
+
+Basically 'all' is an alias for '*'.  It is also possible to address a specific host or hosts::
+
+    one.example.com
+    one.example.com:two.example.com
+    192.168.1.50
+    192.168.1.*
+
+The following patterns address one or more groups, which are denoted
+with the aforementioned bracket headers in the inventory file::
+
+    webservers
+    webservers:dbservers
+
+You can exclude groups as well, for instance, all webservers not in Phoenix::
+
+    webservers:!phoenix
+
+You can also specify the intersection of two groups::
+
+    webservers:&staging
+
+You can do combinations::
+
+    webservers:dbservers:!phoenix:&staging
+
+You can also use variables::
+
+    webservers:!$excluded:&$required
+
+Individual host names, IPs and groups, can also be referenced using
+wildcards::
+
+    *.example.com
+    *.com
+
+It's also ok to mix wildcard patterns and groups at the same time::
+
+    one*.com:dbservers
+
+
+Easy enough.  See :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
+
+Host Variables
+++++++++++++++
+
+It is easy to assign variables to hosts that will be used later in playbooks::
+
+   [atlanta]
+   host1 http_port=80 maxRequestsPerChild=808
+   host2 http_port=303 maxRequestsPerChild=909
+
+
+Group Variables
++++++++++++++++
+
+Variables can also be applied to an entire group at once::
+
+   [atlanta]
+   host1
+   host2
+
+   [atlanta:vars]
+   ntp_server=ntp.atlanta.example.com
+   proxy=proxy.atlanta.example.com
+
+Groups of Groups, and Group Variables
++++++++++++++++++++++++++++++++++++++
+
+It is also possible to make groups of groups and assign
+variables to groups.  These variables can be used by /usr/bin/ansible-playbook, but not
+/usr/bin/ansible::
+
+   [atlanta]
+   host1
+   host2
+
+   [raleigh]
+   host2
+   host3
+
+   [southeast:children]
+   atlanta
+   raleigh
+
+   [southeast:vars]
+   some_server=foo.southeast.example.com
+   halon_system_timeout=30
+   self_destruct_countdown=60
+   escape_pods=2
+
+   [usa:children]
+   southeast
+   northeast
+   southwest
+   southeast
+
+If you need to store lists or hash data, or prefer to keep host and group specific variables
+separate from the inventory file, see the next section.
+
+Splitting Out Host and Group Specific Data
+++++++++++++++++++++++++++++++++++++++++++
+
+.. versionadded:: 0.6
+
+In addition to the storing variables directly in the INI file, host
+and group variables can be stored in individual files relative to the
+inventory file.  These variable files are in YAML format.
+
+Assuming the inventory file path is::
+
+    /etc/ansible/hosts
+
+If the host is named 'foosball', and in groups 'raleigh' and 'webservers', variables
+in YAML files at the following locations will be made available to the host::
+
+    /etc/ansible/group_vars/raleigh
+    /etc/ansible/group_vars/webservers
+    /etc/ansible/host_vars/foosball
+
+For instance, suppose you have hosts grouped by datacenter, and each datacenter
+uses some different servers.  The data in the groupfile '/etc/ansible/group_vars/raleigh' for
+the 'raleigh' group might look like::
+
+    ---
+    ntp_server: acme.example.org
+    database_server: storage.example.org
+
+It is ok if these files do not exist, this is an optional feature.
+
+Tip: Keeping your inventory file and variables in a git repo (or other version control)
+is an excellent way to track changes to your inventory and host variables.
+
+.. versionadded:: 0.5
+   If you ever have two python interpreters on a system, or your Python version 2 interpreter is not found
+   at /usr/bin/python, set an inventory variable called 'ansible_python_interpreter' to the Python
+   interpreter path you would like to use.
+
+.. seealso::
+
+   :doc:`examples`
+       Examples of basic commands
+   :doc:`playbooks`
+       Learning ansible's configuration management language
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+

docsite/rst/playbooks.rst

@@ -0,0 +1,467 @@
+Playbooks
+=========
+
+.. image:: http://ansible.cc/docs/_static/ansible_fest_2013.png
+   :alt: ansiblefest 2013
+   :target: http://ansibleworks.com/fest
+
+
+.. contents::
+   :depth: 2
+   :backlinks: top
+
+Introduction
+````````````
+
+Playbooks are a completely different way to use ansible than in task execution mode, and are
+particularly powerful. Simply put, playbooks are the basis for a really simple
+configuration management and multi-machine deployment system,
+unlike any that already exist, and one that is very well suited to deploying complex applications.
+
+Playbooks can declare configurations, but they can also orchestrate steps of
+any manual ordered process, even as different steps must bounce back and forth
+between sets of machines in particular orders.  They can launch tasks
+synchronously or asynchronously.
+
+While you might run the main /usr/bin/ansible program for ad-hoc
+tasks, playbooks are more likely to be kept in source control and used
+to push out your configuration or assure the configurations of your
+remote systems are in spec.
+
+Let's dive in and see how they work.  As you go, you may wish to open
+the `github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_ in
+another tab, so you can apply the theory to what things look like in practice.
+
+There are also some full sets of playbooks illustrating a lot of these techniques in the
+`ansible-examples repository <https://github.com/ansible/ansible-examples>`_.
+
+Playbook Language Example
+`````````````````````````
+
+Playbooks are expressed in YAML format and have a minimum of syntax.
+Each playbook is composed of one or more 'plays' in a list.
+
+The goal of a play is map a group of hosts to some well defined roles, represented by
+things ansible called tasks.  At the basic level, a task is nothing more than a call
+to an ansible module, which you should have learned about in earlier chapters.
+
+By composing a playbook of multiple 'plays', it is possible to
+orchestrate multi-machine deployments, running certain steps on all
+machines in the webservers group, then certain steps on the database
+server group, then more commands back on the webservers group, etc.
+
+For starters, here's a playbook that contains just one play::
+
+    ---
+    - hosts: webservers
+      vars:
+        http_port: 80
+        max_clients: 200
+      user: root
+      tasks:
+      - name: ensure apache is at the latest version
+        action: yum pkg=httpd state=latest
+      - name: write the apache config file
+        action: template src=/srv/httpd.j2 dest=/etc/httpd.conf
+        notify:
+        - restart apache
+      - name: ensure apache is running
+        action: service name=httpd state=started
+      handlers:
+        - name: restart apache
+          action: service name=httpd state=restarted
+
+Below, we'll break down what the various features of the playbook language are.
+
+Basics
+``````
+
+Hosts and Users
++++++++++++++++
+
+For each play in a playbook, you get to choose which machines in your infrastructure
+to target and what remote user to complete the steps (called tasks) as.
+
+The `hosts` line is a list of one or more groups or host patterns,
+separated by colons, as described in the :ref:`patterns`
+documentation.  The `user` is just the name of the user account::
+
+    ---
+    - hosts: webservers
+      user: root
+
+
+Support for running things from sudo is also available::
+
+    ---
+    - hosts: webservers
+      user: yourname
+      sudo: yes
+
+You can also login as you, and then sudo to different users than root::
+
+    ---
+    - hosts: webservers
+      user: yourname
+      sudo: yes
+      sudo_user: postgres
+
+If you need to specify a password to sudo, run `ansible-playbook` with ``--ask-sudo-pass`` (`-K`).
+If you run a sudo playbook and the playbook seems to hang, it's probably stuck at the sudo prompt.
+Just `Control-C` to kill it and run it again with `-K`.
+
+.. important::
+
+   When using `sudo_user` to a user other than root, the module
+   arguments are briefly written into a random tempfile in /tmp.
+   These are deleted immediately after the command is executed.  This
+   only occurs when sudoing from a user like 'bob' to 'timmy', not
+   when going from 'bob' to 'root', or logging in directly as 'bob' or
+   'root'.  If this concerns you that this data is briefly readable
+   (not writeable), avoid transferring uncrypted passwords with
+   `sudo_user` set.  In other cases, '/tmp' is not used and this does
+   not come into play. Ansible also takes care to not log password
+   parameters.
+
+Vars section
+++++++++++++
+
+The `vars` section contains a list of variables and values that can be used in the plays, like this::
+
+    ---
+    - hosts: webservers
+      user: root
+      vars:
+         http_port: 80
+         van_halen_port: 5150
+         other: 'magic'
+
+These variables can be used later in the playbook like this::
+
+    $varname or ${varname}
+
+The later is useful in the event you need to do something like ${other}_some_string.
+
+Inside templates, the full power of the `Jinja2 <http://jinja.pocoo.org/docs/>`_ templating language is also available, which looks like this::
+
+    {{ varname }}
+
+The Jinja2 documentation provides information about how to construct loops and conditionals for those
+who which to use more advanced templating.  This is optional and the $varname format still works in template
+files.
+
+If there are discovered variables about the system, called 'facts', these variables bubble up back into the
+playbook, and can be used on each system just like explicitly set variables.  Ansible provides several
+of these, prefixed with 'ansible', and are documented under 'setup' in the module documentation.  Additionally,
+facts can be gathered by ohai and facter if they are installed.  Facter variables are prefixed with ``facter_`` and Ohai
+variables are prefixed with ``ohai_``.
+
+So for instance, if I wanted
+to write the hostname into the /etc/motd file, I could say::
+
+   - name: write the motd
+     action: template src=/srv/templates/motd.j2 dest=/etc/motd
+
+And in /srv/templates/motd.j2::
+
+   You are logged into {{ facter_hostname }}
+
+But we're getting ahead of ourselves.  Let's talk about tasks.
+
+Tasks list
+++++++++++
+
+Each play contains a list of tasks.  Tasks are executed in order, one
+at a time, against all machines matched by the host pattern,
+before moving on to the next task.  It is important to understand that, within a play,
+all hosts are going to get the same task directives.  It is the purpose of a play to map
+a selection of hosts to tasks.
+
+When running the playbook, which runs top to bottom, hosts with failed tasks are
+taken out of the rotation for the entire playbook.  If things fail, simply correct the playbook file and rerun.
+
+The goal of each task is to execute a module, with very specific arguments.
+Variables, as mentioned above, can be used in arguments to modules.
+
+Modules are 'idempotent', meaning if you run them
+again, they will make the changes they are told to make to bring the
+system to the desired state.  This makes it very safe to rerun
+the same playbook multiple times.  They won't change things
+unless they have to change things.
+
+The `command` and `shell` modules will typically rerun the same command again,
+which is totally ok if the command is something like
+'chmod' or 'setsebool', etc.  Though there is a 'creates' flag available which can
+be used to make these modules also idempotent.
+
+Every task should have a `name`, which is included in the output from
+running the playbook.   This is output for humans, so it is
+nice to have reasonably good descriptions of each task step.  If the name
+is not provided though, the string fed to 'action' will be used for
+output.
+
+Here is what a basic task looks like, as with most modules,
+the service module takes key=value arguments::
+
+   tasks:
+     - name: make sure apache is running
+       action: service name=httpd state=running
+
+The `command` and `shell` modules are the one modules that just takes a list
+of arguments, and don't use the key=value form.  This makes
+them work just like you would expect. Simple::
+
+   tasks:
+     - name: disable selinux
+       action: command /sbin/setenforce 0
+
+The command and shell module care about return codes, so if you have a command
+who's successful exit code is not zero, you may wish to do this::
+
+   tasks:
+     - name: run this command and ignore the result
+       action: shell /usr/bin/somecommand || /bin/true
+
+Or this::
+
+   tasks:
+     - name: run this command and ignore the result
+       action: shell /usr/bin/somecommand
+       ignore_errors: True
+
+
+If the action line is getting too long for comfort you can break it on
+a space and indent any continuation lines::
+
+    tasks:
+      - name: Copy ansible inventory file to client
+        action: copy src=/etc/ansible/hosts dest=/etc/ansible/hosts
+                owner=root group=root mode=0644
+
+Variables can be used in action lines.   Suppose you defined
+a variable called 'vhost' in the 'vars' section, you could do this::
+
+   tasks:
+     - name: create a virtual host file for $vhost
+       action: template src=somefile.j2 dest=/etc/httpd/conf.d/$vhost
+
+Those same variables are usable in templates, which we'll get to later.
+
+Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually
+make more sense to break up tasks using the 'include:' directive.  We'll show that a bit later.
+
+Action Shorthand
+````````````````
+
+.. versionadded: 0.8
+
+Rather than listing out the explicit word, "action:", like so::
+
+    action: template src=templates/foo.j2 dest=/etc/foo.conf
+
+It is also possible to say:
+
+    template: src=templates/foo.j2 dest=/etc/foo.conf
+
+The name of the module is simply followed by a colon and the arguments to that module.  We think this is a lot more intuitive.  
+Our documentation has not converted over to this new format just yet as many users may still be using older versions.  
+You'll be able to use both formats forever.
+
+Running Operations On Change
+````````````````````````````
+
+As we've mentioned, modules are written to be 'idempotent' and can relay  when
+they have made a change on the remote system.   Playbooks recognize this and
+have a basic event system that can be used to respond to change.
+
+These 'notify' actions are triggered at the end of each 'play' in a playbook, and
+trigger only once each.  For instance, multiple resources may indicate
+that apache needs to be restarted, but apache will only be bounced once.
+
+Here's an example of restarting two services when the contents of a file
+change, but only if the file changes::
+
+   - name: template configuration file
+     action: template src=template.j2 dest=/etc/foo.conf
+     notify:
+        - restart memcached
+        - restart apache
+
+The things listed in the 'notify' section of a task are called
+handlers.
+
+Handlers are lists of tasks, not really any different from regular
+tasks, that are referenced by name.  Handlers are what notifiers
+notify.  If nothing notifies a handler, it will not run.  Regardless
+of how many things notify a handler, it will run only once, after all
+of the tasks complete in a particular play.
+
+Here's an example handlers section::
+
+    handlers:
+        - name: restart memcached
+          action: service name=memcached state=restarted
+        - name: restart apache
+          action: service name=apache state=restarted
+
+Handlers are best used to restart services and trigger reboots.  You probably
+won't need them for much else.
+
+.. note::
+   Notify handlers are always run in the order written.
+
+
+Task Include Files And Encouraging Reuse
+````````````````````````````````````````
+
+Suppose you want to reuse lists of tasks between plays or playbooks.  You can use
+include files to do this.  Use of included task lists is a great way to define a role
+that system is going to fulfill.  Remember, the goal of a play in a playbook is to map
+a group of systems into multiple roles.  Let's see what this looks like...
+
+A task include file simply contains a flat list of tasks, like so::
+
+    ---
+    # possibly saved as tasks/foo.yml
+    - name: placeholder foo
+      action: command /bin/foo
+    - name: placeholder bar
+      action: command /bin/bar
+
+Include directives look like this, and can be mixed in with regular tasks in a playbook::
+
+   tasks:
+    - include: tasks/foo.yml
+
+You can also pass variables into includes.  We call this a 'parameterized include'.
+
+For instance, if deploying multiple wordpress instances, I could
+contain all of my wordpress tasks in a single wordpress.yml file, and use it like so::
+
+   tasks:
+     - include: wordpress.yml user=timmy
+     - include: wordpress.yml user=alice
+     - include: wordpress.yml user=bob
+
+Variables passed in can then be used in the included files.  You can reference them like this::
+
+   $user
+
+(In addition to the explicitly passed in parameters, all variables from
+the vars section are also available for use here as well.)
+
+Starting in 1.0, variables can also be passed to include files using an alternative syntax,
+which also supports structured variables::
+
+    tasks:
+
+      - include: wordpress.yml
+        vars:
+            user: timmy
+            some_list_variable: 
+              - alpha
+              - beta
+              - gamma
+
+Playbooks can include other playbooks too, but that's mentioned in a later section.
+
+.. note::
+   As of 1.0, task include statements can be used at arbitrary depth.
+   They were previously limited to a single level, so task includes
+   could not include other files containing task includes.
+
+Includes can also be used in the 'handlers' section, for instance, if you
+want to define how to restart apache, you only have to do that once for all
+of your playbooks.  You might make a handlers.yml that looks like::
+
+   ---
+   # this might be in a file like handlers/handlers.yml
+   - name: restart apache
+     action: service name=apache state=restarted
+
+And in your main playbook file, just include it like so, at the bottom
+of a play::
+
+   handlers:
+     - include: handlers/handlers.yml
+
+You can mix in includes along with your regular non-included tasks and handlers.
+
+Includes can also be used to import one playbook file into another. This allows
+you to define a top-level playbook that is composed of other playbooks.
+
+For example::
+
+    - name: this is a play at the top level of a file
+      hosts: all
+      user: root
+      tasks:
+      - name: say hi
+        tags: foo
+        action: shell echo "hi..."
+
+    - include: load_balancers.yml
+    - include: webservers.yml
+    - include: dbservers.yml
+
+Note that you cannot do variable substitution when including one playbook
+inside another.
+
+.. note::
+
+   You can not conditionally path the location to an include file,
+   like you can with 'vars_files'.  If you find yourself needing to do
+   this, consider how you can restructure your playbook to be more
+   class/role oriented.  This is to say you cannot use a 'fact' to
+   decide what include file to use.  All hosts contained within the
+   play are going to get the same tasks.  ('only_if' provides some
+   ability for hosts to conditionally skip tasks).
+
+Executing A Playbook
+````````````````````
+
+Now that you've learned playbook syntax, how do you run a playbook?  It's simple.
+Let's run a playbook using a parallelism level of 10::
+
+    ansible-playbook playbook.yml -f 10
+
+Tips and Tricks
+```````````````
+
+Look at the bottom of the playbook execution for a summary of the nodes that were executed
+and how they performed.   General failures and fatal "unreachable" communication attempts are
+kept separate in the counts.
+
+If you ever want to see detailed output from successful modules as well as unsuccessful ones,
+use the '--verbose' flag.  This is available in Ansible 0.5 and later.
+
+Also, in version 0.5 and later, Ansible playbook output is vastly upgraded if the cowsay
+package is installed.  Try it!
+
+In version 0.7 and later, to see what hosts would be affected by a playbook before you run it, you
+can do this::
+
+    ansible-playbook playbook.yml --list-hosts.
+
+.. seealso::
+
+   :doc:`YAMLSyntax`
+       Learn about YAML syntax
+   :doc:`playbooks`
+       Review the basic Playbook language features
+   :doc:`playbooks2`
+       Learn about Advanced Playbook Features
+   :doc:`bestpractices`
+       Various tips about managing playbooks in the real world
+   :doc:`modules`
+       Learn about available modules
+   :doc:`moduledev`
+       Learn how to extend Ansible by writing your own modules
+   :doc:`patterns`
+       Learn about how to select hosts
+   `Github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_
+       Complete playbook files from the github project source
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+
+

examples/DOCUMENTATION.yaml

@@ -0,0 +1,33 @@
+---
+# If a key doesn't apply to your module (ex: choices, default, or
+# aliases) you can use the word 'null', or an empty list, [], where
+# appropriate.
+module: modulename
+short_description: This is a sentence describing the module
+description:
+    - Longer description of the module
+    - You might include instructions
+version_added: X.Y
+author: Your AWESOME name here
+notes:
+    - Other things consumers of your module should know
+requirements:
+    - list of required things
+    - like the factor package
+    - or a specic platform
+options:
+# One or more of the following
+    option_name:
+        description:
+            - Words go here
+            - that describe
+            - this option
+        required: true or false
+        default: a string or the word null
+        choices: [list, of, choices]
+        aliases: [list, of, aliases]
+        version_added: 0.X
+examples:
+# One or more of the following:
+    - code: modulename opt1=arg1 opt2=arg2
+      description: Optional words describing this example

examples/ansible.cfg

@@ -21,7 +21,7 @@ module_name = command
 
 remote_tmp = $HOME/.ansible/tmp
 
-# the default pattern for ansible-playbooks ("hosts:") 
+# the default pattern for ansible-playbooks ("hosts:")
 
 pattern = *
 
@@ -46,6 +46,16 @@ poll_interval=15
 
 sudo_user=root
 
+# the following forces ansible to always ask for the sudo password (instead of having
+# to add -K to the commandline). Or you can use the environment variable (ANSIBLE_ASK_SUDO_PASS)
+
+#ask_sudo_pass=True
+
+# the following forces ansible to always ask for the ssh-password (-k)
+# can also be set by the environment variable ANSIBLE_ASK_PASS
+
+#ask_pass=True
+
 # connection to use when -c <connection_type> is not specified
 
 transport=paramiko
@@ -61,11 +71,53 @@ remote_port=22
 
 #remote_user=root
 
+# the default sudo executable. If a sudo alternative with a sudo-compatible interface
+# is used, specify its executable name as the default
+
+sudo_exe=sudo
+
+# the default flags passed to sudo
+# sudo_flags=-H
+
+# how to handle hash defined in several places
+# hash can be merged, or replaced
+# if you use replace, and have multiple hashes named 'x', the last defined
+# will override the previously defined one
+# if you use merge here, hash will cumulate their keys, but keys will still
+# override each other
+# replace is the default value, and is how ansible always handled hash variables
+#
+# hash_behaviour=replace
+
+# if you need to use jinja2 extensions, you can list them here
+# use a coma to separate extensions, e.g. :
+# jinja2_extensions=jinja2.ext.do,jinja2.ext.i18n
+# no extensions are loaded by default
+
+#jinja2_extensions=
+
 # if set, always use this private key file for authentication, same as if passing
-# --private-key-file to ansible or ansible-playbook
+# --private-key to ansible or ansible-playbook
 
 #private_key_file=/path/to/file
 
+# format of string $ansible_managed available within Jinja2 templates, replacing
+# {file}, {host} and {uid} with template filename, host and owner respectively.
+# The resulting string is passed through strftime(3) so it may contain any
+# time-formatting specifiers.
+#
+# Example: ansible_managed = DONT TOUCH {file}: call {uid} at {host} for changes
+ansible_managed = Ansible managed: {file} modified on %Y-%m-%d %H:%M:%S by {uid} on {host}
+
+# additional plugin paths for non-core plugins
+
+action_plugins     = /usr/share/ansible_plugins/action_plugins
+callback_plugins   = /usr/share/ansible_plugins/callback_plugins
+connection_plugins = /usr/share/ansible_plugins/connection_plugins
+lookup_plugins     = /usr/share/ansible_plugins/lookup_plugins
+vars_plugins       = /usr/share/ansible_plugins/vars_plugins
+filter_plugins     = /usr/share/ansible_plugins/filter_plugins
+
 [paramiko_connection]
 
 # nothing to configure yet
@@ -78,4 +130,8 @@ remote_port=22
 
 ssh_args=-o PasswordAuthentication=no -o ControlMaster=auto -o ControlPersist=60s -o ControlPath=/tmp/ansible-ssh-%h-%p-%r
 
+# the following makes ansible use scp if the connection type is ssh (default is sftp)
+
+#scp_if_ssh=True
+
 

examples/playbooks/ansible_pull.yml

@@ -1,4 +1,4 @@
-# ansibple-pull setup
+# ansible-pull setup
 #
 # on remote hosts, set up ansible to run periodically using the latest code
 # from a particular checkout, in pull based fashion, inverting Ansible's
@@ -20,12 +20,15 @@
 
   vars:
 
-    # schdule is fed directly to cron
+    # schedule is fed directly to cron
     schedule: '*/15 * * * *'
 
     # User to run ansible-pull as from cron
     cron_user: root
 
+    # File that ansible will use for logs
+    logfile: /var/log/ansible-pull.log
+
     # Directory to where repository will be cloned
     workdir: /var/lib/ansible/local
 
@@ -47,5 +50,7 @@
               owner=root group=root mode=0644
 
     - name: Create crontab entry to clone/pull git repository
-      action: template src=templates/ansible-pull.j2 dest=/etc/cron.d/ansible-pull owner=root group=root mode=0644
+      action: template src=templates/etc_cron.d_ansible-pull.j2 dest=/etc/cron.d/ansible-pull owner=root group=root mode=0644
 
+    - name: Create logrotate entry for ansible-pull.log
+      action: template src=templates/etc_logrotate.d_ansible-pull.j2 dest=/etc/logrotate.d/ansible-pull owner=root group=root mode=0644

examples/playbooks/cloudformation.yaml

@@ -0,0 +1,45 @@
+---
+# This playbook demonstrates how to use the ansible cloudformation module to launch an AWS CloudFormation stack.
+#
+# This module requires that the boto python library is installed, and that you have your AWS credentials
+# in $HOME/.boto
+
+#The thought here is to bring up a bare infrastructure with CloudFormation, but use ansible to configure it.
+#I generally do this in 2 different playbook runs as to allow the ec2.py inventory to be updated.
+
+#This module also uses "complex arguments" which were introduced in ansible 1.1 allowing you to specify the
+#Cloudformation template parameters
+
+#This example launches a 3 node AutoScale group, with a security group, and an InstanceProfile with root permissions.
+
+#If a stack does not exist, it will be created.  If it does exist and the template file has changed, the stack will be updated.
+#If the parameters are different, the stack will also be updated.
+
+#CloudFormation stacks can take awhile to provision, if you are curious about its status, use the AWS
+#web console or one of the CloudFormation CLI's.
+
+#Example update -- try first launching the stack with 3 as the ClusterSize.  After it is launched, change it to 4
+#and run the playbook again.
+
+- name: provision stack
+  hosts: localhost
+  connection: local
+  gather_facts: false
+
+  # Launch the cloudformation-example.json template.  Register the output.
+
+  tasks:
+  - name: launch ansible cloudformation example
+    cloudformation: >
+      stack_name="ansible-cloudformation" state=present
+      region=us-east-1 disable_rollback=true
+      template=files/cloudformation-example.json
+    args:
+      template_parameters:
+        KeyName: jmartin
+        DiskType: ephemeral
+        InstanceType: m1.small
+        ClusterSize: 3
+    register: stack
+  - name: show stack outputs
+    debug: msg="My stack outputs are ${stack.stack_outputs}"

examples/playbooks/complex_args.yml

@@ -0,0 +1,55 @@
+---
+
+# this is a bit of an advanced topic.
+#
+# generally Ansible likes to pass simple key=value arguments to modules.  It occasionally comes up though
+# that you might want to write a module that takes COMPLEX arguments, like lists and dictionaries.
+#
+# happen, at least right now, it should be a Python module, so it can leverage some common code in Ansible that
+# makes this easy.  If you write a non-Python module, you can still pass data across, but only hashes that
+# do not contain lists or other hashes.  If you write the Python module, you can do anything.
+#
+# note that if you were to use BOTH the key=value form and the 'args' form for passing data in, the key=value
+# parameters take a higher priority, so you can use them for defaults, which can be useful.
+
+- hosts: all
+  user: root
+  gather_facts: no
+ 
+  vars:
+    defaults:
+      state: stopped
+    complex:
+      ghostbusters: [ 'egon', 'ray', 'peter', 'winston' ]
+      mice: [ 'pinky', 'brain', 'larry' ]
+ 
+  tasks:
+
+    - name: this is the basic way data passing works for any module
+      action: ping data='Hi Mom'
+
+    - name: of course this can also be written like so, which is shorter
+      ping: data='Hi Mom'
+
+    - name: but what if you have a complex module that needs complicated data?
+      action: ping
+      args:
+         data: 
+           moo: cow
+           asdf: [1,2,3,4]
+
+    - name: can we make that cleaner? sure!
+      action: ping
+      args: { data: $complex }
+
+    - name: or if you prefer... this is equivalent
+      action: ping
+      args: 
+          data: $complex
+
+    - name: here is an example of how it works with defaults, notice the key=value format wins
+      action: service name=httpd state=running
+      args: $defaults
+
+
+

examples/playbooks/conditionals_part2.yml

@@ -1,47 +1,54 @@
 ---
-# this is a demo of conditional executions using 'only_if', which can skip
-# certain tasks on machines/platforms/etc where they do not apply.
+# this is a demo of conditional executions using 'when' statements, which can skip
+# certain tasks on machines/platforms/etc where they do not apply.  
 
 - hosts: all
   user: root
 
   vars:
      favcolor: "red"
+     dog: "fido"
+     cat: "whiskers"
      ssn: 8675309
 
-# Below we're going to define some expressions.
+# These are the types of when statemnets available
+#     when_set: $variable_name
+#     when_unset: $variable_name
+#     when_str: $x == "test"
+#     when_int: $y > 2
+#     when_float: $z => 2.3
 #
-# Not only can we assign variables for reuse, but we can also assign conditional
-# expressions.  By keeping these in 'vars', the task section remains
-# extraordinarily clean, and not littered with programming language
-# constructs -- so it's easily skimmed by humans.
+# when using 'when', take care to make sure any variables given are surrounded by spaces
+# as an example, $z>3 will not do what you want, use "$z > 3"
 #
-# Remember to quote any variables if they are not numbers!
-#
-# Interesting fact: aside from the $variables, these expressions are actually
-# tiny bits of Python.  They are evaluated in the context of each host, so different
-# steps can be skipped on different hosts!  They should evaluate to either True
-# or False
-
-     is_favcolor_blue: "'$favcolor' == 'blue'"
-     is_centos: "'$facter_operatingsystem' == 'CentOS'"
-
-# NOTE:
-#
-# facter and ohai variables can be used in only_if statements too
-# ex:  "'$facter_operatingsystem' == 'CentOS'", which bubble up automatically
-# from the managed machines
-#
-# this example won't do that though, as you might not have facter or ohai,
-# but you get the idea...
+# note, if you are doing comparisons to variables that are stored as hashes or lists,
+# you will need to use the older 'only_if', which is more free form.  
+# see conditionals_part_3.yml
 
   tasks:
 
-     - name: "do this if my favcolor is blue"
+     - name: "do this if my favcolor is blue, and my dog is named fido"
        action: shell /bin/false
-       only_if: '$is_favcolor_blue'
+       when_string: $favcolor == 'blue' and $dog == 'fido'
 
-     - name: "do this if my favcolor is not blue"
+     - name: "do this if my favcolor is not blue, and my dog is named fido"
        action: shell /bin/true
-       only_if: 'not ($is_favcolor_blue)'
+       when_string: $favcolor != 'blue' and $dog == 'fido'
+
+     - name: "do this if my SSN is over 9000"
+       action: shell /bin/true
+       when_integer: $ssn > 9000
+
+     - name: "do this if I have one of these SSNs"
+       action: shell /bin/true
+       when_integer:  $ssn in [ 8675309, 8675310, 8675311 ]
+     
+     - name: "do this if a variable named hippo is NOT defined"
+       action: shell /bin/true
+       when_unset: $hippo
+
+     - name: "do this if a variable named hippo is defined"
+       action: shell /bin/true
+       when_set: $hippo
+
 

examples/playbooks/conditionals_part3.yml

@@ -0,0 +1,47 @@
+---
+# this is a demo of conditional executions using 'only_if', which can skip
+# certain tasks on machines/platforms/etc where they do not apply.  This is
+# the more 'raw' version of the 'when' statement, most users will be able to
+# use 'when' directly.  'only_if' is an older feature, and useful for when
+# you need more advanced expression control.
+
+- hosts: all
+  user: root
+
+  vars:
+     favcolor: "red"
+     ssn: 8675309
+
+# Below we're going to define some expressions.
+#
+# Not only can we assign variables for reuse, but we can also assign conditional
+# expressions.  By keeping these in 'vars', the task section remains
+# extraordinarily clean, and not littered with programming language
+# constructs -- so it's easily skimmed by humans.
+#
+# Remember to quote any variables if they are not numbers!
+#
+# Interesting fact: aside from the $variables, these expressions are actually
+# tiny bits of Python.  They are evaluated in the context of each host, so different
+# steps can be skipped on different hosts!  They should evaluate to either True
+# or False
+
+     is_favcolor_blue: "'$favcolor' == 'blue'"
+     is_centos: "'$facter_operatingsystem' == 'CentOS'"
+
+# NOTE:
+#
+# setup module values, facter and ohai variables can be used in only_if statements too
+# ex:  "'$facter_operatingsystem' == 'CentOS'", which bubble up automatically
+# from the managed machines.  This example doesn't do that though.
+
+  tasks:
+
+     - name: "do this if my favcolor is blue"
+       action: shell /bin/false
+       only_if: '$is_favcolor_blue'
+
+     - name: "do this if my favcolor is not blue"
+       action: shell /bin/true
+       only_if: 'not ($is_favcolor_blue)'
+

examples/playbooks/custom_filters.yml

@@ -0,0 +1,6 @@
+---
+
+- name: Demonstrate custom jinja2 filters
+  hosts: all
+  tasks:
+  - action: template src=templates/custom-filters.j2 dest=/tmp/custom-filters.txt

examples/playbooks/environment.yml

@@ -0,0 +1,32 @@
+---
+
+# it is often useful to be able to set the environment for one command and have that environment be totally
+# different for another.  An example is you might use a HTTP proxy for some packages but not for others.
+#
+# in Ansible 1.1 and later, you can pass the environment to any module using either a dictionary variable
+# or a dictionary itself.
+
+
+- hosts: all
+  user: root
+
+  # here we make a variable named "env" that is a dictionary
+  vars:
+    env: 
+       HI: test2
+       http_proxy=http://proxy.example.com:8080
+
+  tasks:
+
+    # here we just define the dictionary directly and use it
+
+    - shell: echo $HI
+      environment:
+         HI: test1
+
+    # here we are using the $env variable above
+    
+    - shell: echo $HI
+      environment: $env
+
+

examples/playbooks/eucalyptus-ec2.yml

@@ -0,0 +1,53 @@
+---
+# This playbook is an example for deploying multiple instances into EC2/Euca and "doing something" with them.
+#   - uses the ec2 and ec2_vol module.
+#
+# Run this with ansible-playbook and supply the private key for your EC2/Euca user (to access the instance in the second play), e.g:
+# ansible-playbook eucalyptus-ec2-deploy.yml -v --private-key=/path/to/ec2/pri/key
+
+- name: Stage instance(s)
+  hosts: local
+  connection: local
+  user: root
+  gather_facts: false
+
+  vars:
+      keypair: mykeypair
+      instance_type: m1.small
+      security_group: default
+      image: emi-048B3A37
+
+  # Launch 5 instances with the following parameters.  Register the output.
+
+  tasks:
+    - name: Launch instance 
+      local_action: ec2 keypair=$keypair group=$security_group instance_type=$instance_type image=$image wait=true count=5 
+      register: ec2
+    
+    # Use with_items to add each instances public IP to a new hostgroup for use in the next play.
+
+    - name: Add new instances to host group
+      local_action: add_host hostname=${item.public_ip} groupname=deploy
+      with_items: ${ec2.instances}
+
+    # Use the ec2_vol module to create volumes for attachment to each instance. Use with_items to attach to each instance (by returned id) launched previously.
+
+    - name: Create a volume and attach
+      local_action: ec2_vol volume_size=20 instance=${item.id}
+      with_items: ${ec2.instances}
+
+# This play targets the new host group
+
+- name: Configure instance
+  hosts: deploy
+  user: root
+  gather_facts: True
+
+  # Do some stuff on each instance ....
+
+  tasks:
+    - name: Ensure NTP is up and running
+      action: service name=ntpd state=started
+   
+    - name: Install Apache Web Server
+      action: yum pkg=httpd state=latest

examples/playbooks/files/cloudformation-example.json

@@ -0,0 +1,399 @@
+{
+  "Outputs" : {
+    "ClusterSecGroup" : {
+      "Description" : "Name of RegionalManagerSecGroup",
+      "Value" : {
+        "Ref" : "InstanceSecurityGroup"
+      }
+    }
+  },
+  "AWSTemplateFormatVersion" : "2010-09-09",
+  "Description" : "Launches an example cluster",
+  "Mappings" : {
+    "ebs" : {
+      "ap-northeast-1" : {
+        "AMI" : "ami-4e6cd34f"
+      },
+      "ap-southeast-1" : {
+        "AMI" : "ami-a6a7e7f4"
+      },
+      "eu-west-1" : {
+        "AMI" : "ami-c37474b7"
+      },
+      "sa-east-1" : {
+        "AMI" : "ami-1e08d103"
+      },
+      "us-east-1" : {
+        "AMI" : "ami-1624987f"
+      },
+      "us-west-1" : {
+        "AMI" : "ami-1bf9de5e"
+      },
+      "us-west-2" : {
+        "AMI" : "ami-2a31bf1a"
+      }
+    },
+    "ephemeral" : {
+      "ap-northeast-1" : {
+        "AMI" : "ami-5a6cd35b"
+      },
+      "ap-southeast-1" : {
+        "AMI" : "ami-a8a7e7fa"
+      },
+      "eu-west-1" : {
+        "AMI" : "ami-b57474c1"
+      },
+      "sa-east-1" : {
+        "AMI" : "ami-1608d10b"
+      },
+      "us-east-1" : {
+        "AMI" : "ami-e8249881"
+      },
+      "us-west-1" : {
+        "AMI" : "ami-21f9de64"
+      },
+      "us-west-2" : {
+        "AMI" : "ami-2e31bf1e"
+      }
+    }
+  },
+  "Parameters" : {
+    "ClusterSize" : {
+      "Description" : "Number of nodes in the cluster",
+      "Type" : "String"
+    },
+    "DiskType" : {
+      "AllowedValues" : [
+        "ephemeral",
+        "ebs"
+      ],
+      "Default" : "ephemeral",
+      "Description" : "Type of Disk to use ( ephemeral/ebs )",
+      "Type" : "String"
+    },
+    "InstanceType" : {
+      "AllowedValues" : [
+        "t1.micro",
+        "m1.small",
+        "m1.medium",
+        "m1.large",
+        "m1.xlarge",
+        "m2.xlarge",
+        "m2.2xlarge",
+        "m2.4xlarge",
+        "c1.medium",
+        "c1.xlarge",
+        "cc1.4xlarge"
+      ],
+      "ConstraintDescription" : "must be valid instance type. ",
+      "Default" : "m1.large",
+      "Description" : "Type of EC2 instance for cluster",
+      "Type" : "String"
+    },
+    "KeyName" : {
+      "Description" : "Name of an existing EC2 KeyPair to enable SSH access to the cluster",
+      "Type" : "String"
+    }
+  },
+  "Resources" : {
+    "ApplicationWaitCondition" : {
+      "DependsOn" : "ClusterServerGroup",
+      "Properties" : {
+        "Handle" : {
+          "Ref" : "ApplicationWaitHandle"
+        },
+        "Timeout" : "4500"
+      },
+      "Type" : "AWS::CloudFormation::WaitCondition"
+    },
+    "ApplicationWaitHandle" : {
+      "Type" : "AWS::CloudFormation::WaitConditionHandle"
+    },
+    "CFNInitUser" : {
+      "Properties" : {
+        "Path" : "/",
+        "Policies" : [
+          {
+            "PolicyDocument" : {
+              "Statement" : [
+                {
+                  "Action" : [
+                    "cloudformation:DescribeStackResource",
+                    "s3:GetObject"
+                  ],
+                  "Effect" : "Allow",
+                  "Resource" : "*"
+                }
+              ]
+            },
+            "PolicyName" : "AccessForCFNInit"
+          }
+        ]
+      },
+      "Type" : "AWS::IAM::User"
+    },
+    "CFNKeys" : {
+      "Properties" : {
+        "UserName" : {
+          "Ref" : "CFNInitUser"
+        }
+      },
+      "Type" : "AWS::IAM::AccessKey"
+    },
+    "ClusterCommunication1" : {
+      "Properties" : {
+        "FromPort" : "-1",
+        "GroupName" : {
+          "Ref" : "InstanceSecurityGroup"
+        },
+        "IpProtocol" : "icmp",
+        "SourceSecurityGroupName" : {
+          "Ref" : "InstanceSecurityGroup"
+        },
+        "ToPort" : "-1"
+      },
+      "Type" : "AWS::EC2::SecurityGroupIngress"
+    },
+    "ClusterCommunication2" : {
+      "Properties" : {
+        "FromPort" : "1",
+        "GroupName" : {
+          "Ref" : "InstanceSecurityGroup"
+        },
+        "IpProtocol" : "tcp",
+        "SourceSecurityGroupName" : {
+          "Ref" : "InstanceSecurityGroup"
+        },
+        "ToPort" : "65356"
+      },
+      "Type" : "AWS::EC2::SecurityGroupIngress"
+    },
+    "ClusterCommunication3" : {
+      "Properties" : {
+        "FromPort" : "1",
+        "GroupName" : {
+          "Ref" : "InstanceSecurityGroup"
+        },
+        "IpProtocol" : "udp",
+        "SourceSecurityGroupName" : {
+          "Ref" : "InstanceSecurityGroup"
+        },
+        "ToPort" : "65356"
+      },
+      "Type" : "AWS::EC2::SecurityGroupIngress"
+    },
+    "InstanceSecurityGroup" : {
+      "Properties" : {
+        "GroupDescription" : "Enable SSH access via port 22",
+        "SecurityGroupIngress" : [
+          {
+            "CidrIp" : "0.0.0.0/0",
+            "FromPort" : "22",
+            "IpProtocol" : "tcp",
+            "ToPort" : "22"
+          }
+        ]
+      },
+      "Type" : "AWS::EC2::SecurityGroup"
+    },
+    "LaunchConfig" : {
+      "Properties" : {
+        "IamInstanceProfile" : {
+          "Ref" : "RootInstanceProfile"
+        },
+        "ImageId" : {
+          "Fn::FindInMap" : [
+            {
+              "Ref" : "DiskType"
+            },
+            {
+              "Ref" : "AWS::Region"
+            },
+            "AMI"
+          ]
+        },
+        "InstanceType" : {
+          "Ref" : "InstanceType"
+        },
+        "KeyName" : {
+          "Ref" : "KeyName"
+        },
+        "SecurityGroups" : [
+          {
+            "Ref" : "InstanceSecurityGroup"
+          }
+        ],
+        "UserData" : {
+          "Fn::Base64" : {
+            "Fn::Join" : [
+              "\n",
+              [
+                "#!/bin/bash -v",
+                "exec > >(tee /var/log/cfn-data.log|logger -t user-data -s 2>/dev/console) 2>&1",
+                "",
+                "sleep 10",
+                "",
+                "function retry {",
+                "   nTrys=0",
+                "   maxTrys=5",
+                "   status=256",
+                "   until [ $status == 0 ] ; do",
+                "      $1",
+                "      status=$?",
+                "      nTrys=$(($nTrys + 1))",
+                "      if [ $nTrys -gt $maxTrys ] ; then",
+                "            echo \"Number of re-trys exceeded. Exit code: $status\"",
+                "            exit $status",
+                "      fi",
+                "      if [ $status != 0 ] ; then",
+                "            echo \"Failed (exit code $status)... retry $nTrys\"",
+                "            sleep 10",
+                "      fi",
+                "   done",
+                "}",
+                "",
+                "yum update -y aws-cfn-bootstrap",
+                "",
+                "#for all the stuff that complains about sudo and tty",
+                "sed -i 's,Defaults    requiretty,#Defaults    requiretty,g' /etc/sudoers",
+                "",
+                "function error_exit",
+                "{",
+                {
+                  "Fn::Join" : [
+                    "",
+                    [
+                      "  /opt/aws/bin/cfn-signal -e 1 -r \"$1\" '",
+                      {
+                        "Ref" : "ApplicationWaitHandle"
+                      },
+                      "'"
+                    ]
+                  ]
+                },
+                "}",
+                "yum update -y aws-cfn-bootstrap",
+                "#this runs the first stage of cfinit",
+                {
+                  "Fn::Join" : [
+                    "",
+                    [
+                      "#/opt/aws/bin/cfn-init -c ascending -v --region ",
+                      {
+                        "Ref" : "AWS::Region"
+                      },
+                      " -s ",
+                      {
+                        "Ref" : "AWS::StackName"
+                      },
+                      " -r ",
+                      "LaunchConfig",
+                      " --access-key ",
+                      {
+                        "Ref" : "CFNKeys"
+                      },
+                      " --secret-key ",
+                      {
+                        "Fn::GetAtt" : [
+                          "CFNKeys",
+                          "SecretAccessKey"
+                        ]
+                      },
+                      " || error_exit 'Failed to initialize client using cfn-init'"
+                    ]
+                  ]
+                },
+                "",
+                "",
+                "",
+                "result_code=$?",
+                {
+                  "Fn::Join" : [
+                    "",
+                    [
+                      "/opt/aws/bin/cfn-signal -e $result_code '",
+                      {
+                        "Ref" : "ApplicationWaitHandle"
+                      },
+                      "'"
+                    ]
+                  ]
+                }
+              ]
+            ]
+          }
+        }
+      },
+      "Type" : "AWS::AutoScaling::LaunchConfiguration"
+    },
+    "ClusterServerGroup" : {
+      "Properties" : {
+        "AvailabilityZones" : {
+          "Fn::GetAZs" : ""
+        },
+        "LaunchConfigurationName" : {
+          "Ref" : "LaunchConfig"
+        },
+        "MaxSize" : {
+          "Ref" : "ClusterSize"
+        },
+        "MinSize" : {
+          "Ref" : "ClusterSize"
+        }
+      },
+      "Type" : "AWS::AutoScaling::AutoScalingGroup"
+    },
+    "RolePolicies" : {
+      "Properties" : {
+        "PolicyDocument" : {
+          "Statement" : [
+            {
+              "Action" : "*",
+              "Effect" : "Allow",
+              "Resource" : "*"
+            }
+          ]
+        },
+        "PolicyName" : "root",
+        "Roles" : [
+          {
+            "Ref" : "RootRole"
+          }
+        ]
+      },
+      "Type" : "AWS::IAM::Policy"
+    },
+    "RootInstanceProfile" : {
+      "Properties" : {
+        "Path" : "/",
+        "Roles" : [
+          {
+            "Ref" : "RootRole"
+          }
+        ]
+      },
+      "Type" : "AWS::IAM::InstanceProfile"
+    },
+    "RootRole" : {
+      "Properties" : {
+        "AssumeRolePolicyDocument" : {
+          "Statement" : [
+            {
+              "Action" : [
+                "sts:AssumeRole"
+              ],
+              "Effect" : "Allow",
+              "Principal" : {
+                "Service" : [
+                  "ec2.amazonaws.com"
+                ]
+              }
+            }
+          ]
+        },
+        "Path" : "/"
+      },
+      "Type" : "AWS::IAM::Role"
+    }
+  }
+}

examples/playbooks/filter_plugins/custom_plugins.py

@@ -0,0 +1,29 @@
+# (c) 2012, Jeroen Hoekx <jeroen@hoekx.be>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+class FilterModule(object):
+    ''' Custom filters are loaded by FilterModule objects '''
+
+    def filters(self):
+        ''' FilterModule objects return a dict mapping filter names to
+            filter functions. '''
+        return {
+            'generate_answer': self.generate_answer,
+        }
+
+    def generate_answer(self, value):
+        return '42'

examples/playbooks/group_by.yml

@@ -0,0 +1,35 @@
+---
+# Example playbook to demonstrate the group_by action plugin.
+#
+# as we know, the setup module will automatically run in each play, and sets up various
+# facts.  We can then create temporary (in memory only) groups based on those facts, which
+# are useful ways of selecting similar sets of hosts.
+#
+# Additionally, we can use the 'register' keyword in Ansible to set similar variables
+# and use those for grouping.  This is not shown in this example.
+
+- hosts: all
+
+  tasks:
+
+  - name: Create a group of all hosts by operating system
+    action: group_by key=${ansible_distribution}-${ansible_distribution_version}
+
+# the following host group does not exist in inventory and was created by the group_by
+# module.
+
+- hosts: CentOS-6.2
+
+  tasks:
+
+  - name: ping all CentOS 6.2 hosts
+    action: ping
+
+- hosts: CentOS-6.3
+
+  tasks:
+  
+  - name: ping all CentOS 6.3 hosts
+    action: ping
+
+

examples/playbooks/group_commands.yml

@@ -3,7 +3,7 @@
 
 - hosts: all
   user: root
-  sudo: True
+  sudo: yes
 
   tasks:
 

examples/playbooks/intermediate_example.yml

@@ -1,5 +1,5 @@
 ---
-# see examples.yml first!
+# see intro_example.yml first!
 # This file explains some more advanced features of playbooks.
 # because of the comments it's less concise than it normally is.  But feel
 # free to comment your playbooks if you like.
@@ -42,7 +42,9 @@
 
     # handlers can also be included from files, to promote reuse
     # and simpler recipes, you may wish to only have one
-    # handler file for all your plays and playbooks
+    # handler file for all your plays and playbooks.  This example really
+    # doesn't notify any handlers, it is just showing you how they would
+    # be included (see intro_example for usage).
 
     - include: handlers/handlers.yml
 

examples/playbooks/intro_example.yml

@@ -13,7 +13,7 @@
 
 # could have also have done:
 #  user: mdehaan
-#  sudo: True
+#  sudo: yes
 
   # make these variables available inside of templates
   # for when we use the 'template' action/module later on...

examples/playbooks/loop_nested.yml

@@ -0,0 +1,10 @@
+---
+# this is a trivial example of how to do a nested loop.
+
+- hosts: all
+  tasks:
+    - shell: echo "nested test a=${item[0]} b=${item[1]} c=${item[2]}"
+      with_nested:
+        - [ 'red', 'blue', 'green' ]
+        - [ 1, 2, 3 ]
+        - [ 'up', 'down', 'strange']

examples/playbooks/loop_plugins.yml

@@ -0,0 +1,20 @@
+---
+
+# in addition to loop_with_items, the loop that works over a variable, ansible can do more sophisticated looping.
+
+# developer types: these are powered by 'lookup_plugins' should you ever decide to write your own
+# see lib/ansible/runner/lookup_plugins/fileglob.py -- they can do basically anything!
+
+- hosts: all
+  gather_facts: no
+
+  tasks:
+
+    # this will copy a bunch of config files over -- dir must be created first
+
+    - file: dest=/etc/fooapp state=directory
+
+    - copy: src=$item dest=/etc/fooapp/ owner=root mode=600
+      with_fileglob: /playbooks/files/fooapp/* 
+
+

examples/playbooks/netscaler.yml

@@ -0,0 +1,25 @@
+---
+#
+# NetScaler module example
+#
+
+- hosts: web-pool
+  serial: 3
+  vars:
+  	nsc_host: nsc.example.com
+  	nsc_user: admin
+  	nsc_pass: nimda
+  	# type of the netscaler object you want to manipulate
+  	type: service
+  	# netscaler object name
+  	name: ${facter_fqdn}:8080
+
+  tasks:
+  	- name: disable service in the lb
+  	  action: netscaler nsc_host=${nsc_host} user=${nsc_user} password=${nsc_pass} name=${name} type=${type} action=disable
+
+  	- name: deploy new code
+  	  action: shell yum upgrade -y
+
+  	- name: enable in the lb
+  	  action: netscaler nsc_host=${nsc_host} user=${nsc_user} password=${nsc_pass} name=${name} type=${type} action=enable

examples/playbooks/postgresql.yml

@@ -7,8 +7,8 @@
 #
 ---
 - hosts: webservers
-  sudo: True
-  gather_facts: False
+  sudo: yes
+  gather_facts: no
 
   tasks:
   - name: ensure apt cache is up to date
@@ -21,9 +21,9 @@
         - python-psycopg2
 
 - hosts: webservers
-  sudo: True
+  sudo: yes
   sudo_user: postgres
-  gather_facts: False
+  gather_facts: no
 
   vars:
     dbname: myapp
@@ -36,3 +36,6 @@
 
   - name: ensure user has access to database
     action: postgresql_user db=$dbname user=$dbuser password=$dbpassword priv=ALL
+
+  - name: ensure user does not have unnecessary privilege
+    action: postgresql_user user=$dbuser role_attr_flags=NOSUPERUSER,NOCREATEDB

examples/playbooks/prompts.yml

@@ -28,16 +28,18 @@
   vars_prompt:
     - name: "some_password"
       prompt: "Enter password"
-      private: True
+      private: yes
+
     - name: "release_version"
       prompt: "Product release version"
-      private: False
+      default: "my_default_version"
+      private: no
    
     - name: "my_password2"
       prompt: "Enter password2"
-      private: True
+      private: yes
       encrypt: "md5_crypt" 
-      confirm: True
+      confirm: yes
       salt_size: 7
       salt: "foo" 
 
@@ -48,7 +50,7 @@
   tasks:
 
   - name: imagine this did something interesting with $release_version
-    action: shell echo foo >> /tmp/$release_version-$alpha
+    action: shell echo foo >> /tmp/$release_version-alpha
 
   - name: look we crypted a password
     action: shell echo my password is $my_password2

examples/playbooks/rabbitmq.yml

@@ -0,0 +1,39 @@
+---
+- hosts: rabbitmq
+  sudo: true
+  vars:
+    rabbitmq_version: 3.0.2-1
+
+  tasks:
+  - name: ensure python-software-properties is installed
+    apt: pkg=python-software-properties state=installed
+
+  - name: add rabbitmq official apt repository
+    apt_repository: repo='deb http://www.rabbitmq.com/debian/ testing main' state=present
+
+  - name: install rabbitmq
+    apt: pkg=rabbitmq-server=$rabbitmq_version state=installed force=yes
+
+  - name: enable rabbitmq plugins
+    rabbitmq_plugin: names=rabbitmq_management,rabbitmq_tracing,rabbitmq_federation state=enabled
+    notify:
+    - restart rabbitmq
+
+  - name: add users
+    rabbitmq_user: user=$item password=changeme tags=administrator,$item vhost=/ configure_priv=.* write_priv=.* read_priv=.* state=present
+    with_items:
+    - user1
+    - user2
+
+  - name: remove default guest user
+    rabbitmq_user: user=guest state=absent
+
+  - name: ensure vhost /test is present
+    rabbitmq_vhost: name=/test state=present
+
+  - name: set federation local-username
+    rabbitmq_parameter: component=federation name=local-username value='"user1"' state=present
+
+  handlers:
+  - name: restart rabbitmq
+    service: name=rabbitmq-server state=restarted

examples/playbooks/register_logic.yml

@@ -10,20 +10,19 @@
   tasks:
 
       # it is possible to save the result of any command in a named register.  This variable will be made
-      # available to tasks and templates made further down in the execution flow.  Here we save the result
-      # of a simple 'cat' command in a variable called 'motd_contents'
+      # available to tasks and templates made further down in the execution flow.  
 
-      - action: shell cat /etc/motd
-        register: motd_contents
+      - action: shell grep hi /etc/motd
+        ignore_errors: yes
+        register: motd_result
 
-      # and here we access the register.  Note that motd_contents as a variable is structured data because
+      # and here we access the register.  Note that variable is structured data because
       # it is a return from the command module.   The shell module makes available variables such as
-      # as 'stdout', 'stderr', and 'rc'.  Here's a rather trivial example that runs an arbitrary step
-      # if and only if the motd file contained the word 'hi'.   Remember that only_if statements are
-      # Python expressions.  This is as complicated as Ansible syntax is going to get, and the only
-      # time python really seeps into ansible's language.
- 
+      # as 'stdout', 'stderr', and 'rc'.  
+
+      # here we run the next action only if the previous grep returned true
+
       - action: shell echo "motd contains the word hi"
-        only_if: "'${motd_contents.stdout}'.find('hi') != -1"
+        only_if: "${motd_result.rc} == 0"
 
 

examples/playbooks/tasks/base.yml

@@ -19,4 +19,3 @@
 
 - name: made up task just to show variables work here
   action: command /bin/echo release is $release
-

examples/playbooks/templates/custom-filters.j2

@@ -0,0 +1 @@
+1 + 1 = {{ '1+1' | generate_answer }}

examples/playbooks/templates/etc_cron.d_ansible-pull.j2

@@ -1,2 +1,2 @@
 # Cron job to git clone/pull a repo and then run locally
-{{ schedule }} {{ cron_user }} ansible-pull -d {{ workdir }} -U {{ repo_url }} >/var/log/ansible-pull.log 2>&1
+{{ schedule }} {{ cron_user }} ansible-pull -d {{ workdir }} -U {{ repo_url }} >>{{ logfile }} 2>&1