Add some docs/examples

Add a basic ansible-pull man page.

Add the example playbooks/scripts to the RPM package.

Closes #841

MANIFEST.in

@@ -1,6 +1,7 @@
 include README.md packaging/rpm/ansible.spec COPYING
 include examples/hosts
 include examples/ansible.cfg
+graft examples/playbooks
 include packaging/distutils/setup.py
 recursive-include docs *
 recursive-include library *

Makefile

@@ -21,7 +21,7 @@ NAME = "ansible"
 # directory of the target file ($@), kinda like `dirname`.
 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
+MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1
 
 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
 

docs/man/man1/ansible-playbook.1

@@ -1,13 +1,22 @@
 '\" t
 .\"     Title: ansible-playbook
 .\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 08/06/2012
+.\"      Date: 08/14/2012
 .\"    Manual: System administration commands
 .\"    Source: Ansible 0.7
 .\"  Language: English
 .\"
-.TH "ANSIBLE\-PLAYBOOK" "1" "08/06/2012" "Ansible 0\&.7" "System administration commands"
+.TH "ANSIBLE\-PLAYBOOK" "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 '
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------
@@ -36,7 +45,7 @@ The names of one or more YAML format files to run as ansible playbooks\&.
 .sp
 \fB\-v\fR, \fB\-\-verbose\fR
 .sp
-Verbose mode, more output from successful actions will be shown
+Verbose mode, more output from successful actions will be shown\&.
 .PP
 \fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
 .RS 4
@@ -73,7 +82,12 @@ Prompt for the SSH password instead of assuming key\-based authentication with s
 .PP
 \fB\-K\fR, \fB\-\-ask\-sudo\-pass\fR
 .RS 4
-Prompt for the password to use for playbook plays that request sudo access, if any
+Prompt for the password to use for playbook plays that request sudo access, if any\&.
+.RE
+.PP
+\fB\-U\fR, \fISUDO_USER\fR, \fB\-\-sudo\-user=\fR\fISUDO_USER\fR
+.RS 4
+Desired sudo user (default=root)\&.
 .RE
 .PP
 \fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR
@@ -91,6 +105,17 @@ Force all plays to use sudo, even if not marked as such\&.
 .RS 4
 Use this remote user name on playbook steps that do not indicate a user name to run as\&.
 .RE
+.PP
+\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
+.RS 4
+Connection type to use\&. Possible options are
+\fIparamiko\fR
+(SSH),
+\fIssh\fR, and
+\fIlocal\fR\&.
+\fIlocal\fR
+is mostly useful for crontab or kickstarts\&.
+.RE
 .SH "ENVIRONMENT"
 .sp
 The following environment variables may specified\&.
@@ -108,6 +133,6 @@ Copyright \(co 2012, Michael DeHaan
 Ansible is released under the terms of the GPLv3 License\&.
 .SH "SEE ALSO"
 .sp
-\fBansible\fR(1)
+\fBansible\fR(1), \fBansible\-pull\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-playbook.1.asciidoc.in

@@ -122,7 +122,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible*(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-pull.1

@@ -0,0 +1,73 @@
+'\" t
+.\"     Title: ansible
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\"      Date: 08/14/2012
+.\"    Manual: System administration commands
+.\"    Source: Ansible 0.7
+.\"  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 '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+ansible-pull \- set up a remote copy of ansible on each managed node
+.SH "SYNOPSIS"
+.sp
+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\&.
+.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
+The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible\-pull\&.
+.sp
+This is useful both for extreme scale\-out as well as periodic remediation\&. Usage of the \fIfetch\fR module to retrieve logs from ansible\-pull runs would be an excellent way to gather and analyze remote logs from ansible\-pull\&.
+.SH "OPTIONS"
+.PP
+\fB\-d\fR \fIDEST\fR, \fB\-\-directory=\fR\fIDEST\fR
+.RS 4
+Directory to checkout git repository into\&.
+.RE
+.PP
+\fB\-U\fR \fIURL\fR, \fB\-\-url=\fR\fIURL\fR
+.RS 4
+URL of git repository to clone\&.
+.RE
+.PP
+\fB\-C\fR \fICHECKOUT\fR, \fB\-\-checkout=\fR\fICHECKOUT\fR
+.RS 4
+Branch/Tag/Commit to checkout\&. Defaults to
+\fIHEAD\fR\&.
+.RE
+.SH "AUTHOR"
+.sp
+Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
+.SH "COPYRIGHT"
+.sp
+Copyright \(co 2012, Michael DeHaan
+.sp
+Ansible is released under the terms of the GPLv3 License\&.
+.SH "SEE ALSO"
+.sp
+\fBansible\fR(1), \fBansible\-playbook\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-pull.1.asciidoc.in

@@ -0,0 +1,76 @@
+ansible(1)
+=========
+:doctype:manpage
+:man source:   Ansible
+:man version:  %VERSION%
+:man manual:   System administration commands
+
+NAME
+----
+ansible-pull - set up a remote copy of ansible on each managed node
+
+
+SYNOPSIS
+--------
+ansible -d DEST -U URL [ -C CHECKOUT ]
+
+
+DESCRIPTION
+-----------
+
+*Ansible* is an extra-simple tool/framework/API for doing \'remote things' over
+SSH.
+
+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 *push* architecture of ansible into a
+*pull* architecture, which has near-limitless scaling potential.
+
+The setup playbook can be tuned to change the cron frequency, logging
+locations, and parameters to ansible-pull.
+
+This is useful both for extreme scale-out as well as periodic
+remediation. Usage of the 'fetch' module to retrieve logs from
+ansible-pull runs would be an excellent way to gather and analyze
+remote logs from ansible-pull.
+
+
+OPTIONS
+-------
+
+*-d* 'DEST', *--directory=*'DEST'::
+
+Directory to checkout git repository into.
+
+*-U* 'URL', *--url=*'URL'::
+
+URL of git repository to clone.
+
+*-C* 'CHECKOUT', *--checkout=*'CHECKOUT'::
+
+Branch/Tag/Commit to checkout.  Defaults to 'HEAD'.
+
+
+
+AUTHOR
+------
+
+Ansible was originally written by Michael DeHaan. See the AUTHORS file
+for a complete list of contributors.
+
+
+COPYRIGHT
+---------
+
+Copyright © 2012, Michael DeHaan
+
+Ansible is released under the terms of the GPLv3 License.
+
+
+SEE ALSO
+--------
+
+*ansible*(1), *ansible-playbook*(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

@@ -1,13 +1,22 @@
 '\" t
 .\"     Title: ansible
 .\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 08/06/2012
+.\"      Date: 08/14/2012
 .\"    Manual: System administration commands
 .\"    Source: Ansible 0.7
 .\"  Language: English
 .\"
-.TH "ANSIBLE" "1" "08/06/2012" "Ansible 0\&.7" "System administration commands"
+.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 '
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------
@@ -25,7 +34,7 @@ ansible \- run a command somewhere else
 ansible <host\-pattern> [\-f forks] [\-m module_name] [\-a args]
 .SH "DESCRIPTION"
 .sp
-\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&.
+\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq over SSH\&.
 .SH "ARGUMENTS"
 .PP
 \fBhost\-pattern\fR
@@ -49,6 +58,11 @@ Level of parallelism\&.
 is specified as an integer, the default is 5\&.
 .RE
 .PP
+\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
+.RS 4
+Use this file to authenticate the connection\&.
+.RE
+.PP
 \fB\-m\fR \fINAME\fR, \fB\-\-module\-name=\fR\fINAME\fR
 .RS 4
 Execute the module called
@@ -63,7 +77,7 @@ to load modules from\&. The default is
 \fI/usr/share/ansible\fR\&.
 .RE
 .PP
-\fB\-a\fR \'\fIARGUMENTS\fR\', \fB\-\-args=\fR\'\fIARGUMENTS\fR\'
+\fB\-a\fR \*(Aq\fIARGUMENTS\fR\*(Aq, \fB\-\-args=\fR\*(Aq\fIARGUMENTS\fR\*(Aq
 .RS 4
 The
 \fIARGUMENTS\fR
@@ -131,12 +145,20 @@ 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
 \fIparamiko\fR
-(SSH) and
+(SSH),
-\fIlocal\fR\&. Local is mostly useful for crontab or kickstarts\&.
+\fIssh\fR, and
+\fIlocal\fR\&.
+\fIlocal\fR
+is mostly useful for crontab or kickstarts\&.
 .RE
 .SH "INVENTORY"
 .sp
@@ -165,6 +187,6 @@ Copyright \(co 2012, Michael DeHaan
 Ansible is released under the terms of the GPLv3 License\&.
 .SH "SEE ALSO"
 .sp
-\fBansible\-playbook\fR(1)
+\fBansible\-playbook\fR(1), \fBansible\-pull\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.1.asciidoc.in

@@ -160,7 +160,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible-playbook*(1)
+*ansible-playbook*(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/>

packaging/rpm/ansible.spec

@@ -56,7 +56,7 @@ rm -rf $RPM_BUILD_ROOT
 %config(noreplace) %{_sysconfdir}/ansible
 %doc README.md PKG-INFO COPYING
 %doc %{_mandir}/man1/ansible*
-
+%doc examples/playbooks
 
 %changelog
 * Mon Aug 6 2012 Michael DeHaan <michael.dehaan@gmail.com> - 0.7-0