From 55d256d82a5e6ed8a8b7c98f805b8e2767782ed7 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Tue, 28 Feb 2012 04:15:52 -0500 Subject: [PATCH] Added solution to avoid checking in manpages. Just run "make" and we'll build docs before python setup.py. Seems reasonable to let Makefile drive --- Makefile | 10 ++ docs/man/man1/ansible.1 | 96 ----------------- docs/man/man5/ansible-modules.5 | 179 ------------------------------- docs/man/man5/ansible-playbook.5 | 66 ------------ 4 files changed, 10 insertions(+), 341 deletions(-) delete mode 100644 docs/man/man1/ansible.1 delete mode 100644 docs/man/man5/ansible-modules.5 delete mode 100644 docs/man/man5/ansible-playbook.5 diff --git a/Makefile b/Makefile index 93759b60099..6fa152a7d52 100644 --- a/Makefile +++ b/Makefile @@ -5,6 +5,8 @@ ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.5 docs/man/man5/ansible-playbook.5 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()") +all: clean python + docs: manuals manuals: $(MANPAGES) @@ -28,5 +30,13 @@ clean: find ./docs/ -type f -name "*.xml" -delete find . -type f -name "#*" -delete +python: docs + python setup.py build + +install: docs + python setup.py install + .PHONEY: docs manual clean pep8 vpath %.asciidoc docs/man/man1 + + diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1 deleted file mode 100644 index f5bb1a3be86..00000000000 --- a/docs/man/man1/ansible.1 +++ /dev/null @@ -1,96 +0,0 @@ -'\" t -.\" Title: ansible -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 02/28/2012 -.\" Manual: System administration commands -.\" Source: Ansible 0.0.1 -.\" Language: English -.\" -.TH "ANSIBLE" "1" "02/28/2012" "Ansible 0\&.0\&.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 \- run a command somewhere else -.SH "SYNOPSIS" -.sp -ansible [\-f forks] [\-p pattern ] [\-u remote_user] [\-n module_name] [\-a [args1 [args2 \&...]]] -.SH "DESCRIPTION" -.sp -\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&. -.SH "OPTIONS" -.PP -\fB\-k\fR, \fB\-\-ask\-pass\fR -.RS 4 -Ask the user to input the ssh password for connecting\&. Generally using ssh\-agent instead is preferred\&. -.RE -.PP -\fB\-l\fR, \fB\-\-host\-list\fR -.RS 4 -Path to hosts list, which defaults to /etc/ansible/hosts\&. Users can use multiple files to emulate groups of systems\&. -.RE -.PP -\fB\-m\fR, \fB\-\-module\-path\fR -.RS 4 -Override the path to module library, which defaults to /usr/share/ansible\&. The module library contains runnable modules that do -\fIthings\fR -to remote hosts\&. See ansible\-modules(5) for a list of those that bundled with Ansible\&. -.RE -.PP -\fB\-f\fR, \fB\-\-forks\fR -.RS 4 -Level of parallelism\&. Specify as an integer, the default is 3\&. If set to "1" debugging for certain classes of internal errors may become easier\&. -.RE -.PP -\fB\-n\fR, \fB\-\-name\fR -.RS 4 -Module name to execute\&. -.RE -.PP -\fB\-a\fR, \fB\-\-args\fR -.RS 4 -Arguments to module, as a single string\&. Be sure to observe proper shell quoting rules\&. How these are handled are up to the module, but most modules take "key=value" pairs delimited by spaces\&. -.RE -.PP -\fB\-p\fR, \fB\-\-pattern\fR -.RS 4 -Hostname pattern\&. Accepts shell\-like globs which can be seperated with ";" The default is "*" which matches all hosts in the ansible hosts file\&. -.RE -.PP -\fB\-u\fR, \fB\-\-remote\-user\fR -.RS 4 -Remote user to connect as\&. Uses -\fIroot\fR -by default\&. -.RE -.SH "INVENTORY" -.sp -Ansible stores the hosts it can potentially operate on in an inventory file\&. The syntax is simple: one host per line\&. Organize your hosts into multiple groups by separating them into multiple inventory files\&. -.SH "FILES" -.sp -/etc/ansible/hosts \(em Default hosts file -.sp -/usr/share/ansible \(em Default module library -.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\-modules\fR(5), -.sp -\fBansible\-playbook\fR(5), -.sp -Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man5/ansible-modules.5 b/docs/man/man5/ansible-modules.5 deleted file mode 100644 index b538534bc60..00000000000 --- a/docs/man/man5/ansible-modules.5 +++ /dev/null @@ -1,179 +0,0 @@ -'\" t -.\" Title: ansible-modules -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 02/27/2012 -.\" Manual: System administration commands -.\" Source: Ansible-modules 0.0.1 -.\" Language: English -.\" -.TH "ANSIBLE\-MODULES" "5" "02/27/2012" "Ansible\-modules 0\&.0\&.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-modules \- stock modules shipped with ansible -.SH "DESCRIPTION" -.sp -Ansible ships with a number of modules that can be executed directly on remote hosts or through ansible playbooks\&. -.SH "IDEMPOTENCE" -.sp -Most modules other than command are idempotent, meaning they will seek to avoid changes unless a change needs to be made\&. When using ansible playbooks, these modules can trigger change events, as described in ansible\-playbooks (5)\&. -.sp -Unless otherwise noted, all modules support change hooks\&. -.SH "COMMAND" -.sp -The command module takes the command name followed by a list of arguments, space delimited\&. This is the only module that does not use key=value style parameters\&. -.PP -Example usage -.RS 4 -/sbin/shutdown \-t now -.RE -.sp -This module does not support change hooks\&. -.sp -Returns the return code from the program as well as timing information\&. -.sp -(Async command running and command execution time limits are in plan\&.) -.SH "COPY" -.sp -The copy module moves a file on the local box to remote locations\&. -.PP -\fBsrc=\fR -.RS 4 -Local absolute path to a file to copy to the remote server -.RE -.PP -\fBdest=\fR -.RS 4 -Remote absolute path where the file should end up -.RE -.sp -This module also returns md5sum information about the resultant file\&. -.SH "FACTER" -.sp -Runs the discovery program \fIfacter\fR on the remote system, returning JSON data that can be useful for inventory purposes\&. -.sp -Requires that \fIfacter\fR and \fIruby\-json\fR be installed on the remote end\&. -.sp -This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. -.SH "FILE" -.sp -Ensures the ownership and permissions of files are as desired\&. -.sp -Use copy or template first if you need to make sure a file is on the box\&. -.sp -In plan\&. -.SH "GIT" -.sp -Deploys software from git checkouts\&. -.PP -\fBrepo=\fR -.RS 4 -git or http protocol address of the repo to checkout -.RE -.PP -\fBdest=\fR -.RS 4 -where to check it out, an absolute directory path -.RE -.PP -\fBversion=\fR -.RS 4 -what version to check out \(em either the git SHA, the literal string -\fIHEAD\fR, or a tag name -.RE -.SH "OHAI" -.sp -Similar to the facter module, this returns JSON inventory data\&. Ohai data is a bit more verbose and nested than facter\&. -.sp -Requires that \fIohai\fR be installed on the remote end\&. -.sp -This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. -.SH "PING" -.sp -A trivial test module, this module always returns the integer \fI1\fR on successful contact\&. -.sp -This module does not support change hooks\&. -.sp -This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. -.SH "SERVICE" -.sp -Controls services on remote machines\&. -.PP -\fBstate=\fR -.RS 4 -Values are -\fIstarted\fR, -\fIstopped\fR, or -\fIrestarted\fR\&. Started/stopped are idempotent actions that will not run commands unless neccessary\&. -\fIrestarted\fR -will always bounce the service -.RE -.PP -\fBname=\fR -.RS 4 -The name of the service -.RE -.SH "SETUP" -.sp -Writes a JSON file containing key/value data, for use in templating\&. Call this once before using the template modules, usually as the very first step in your playbook\&. -.sp -If facter or ohai are installed, variables from these programs will also be snapshotted into the JSON file for usage in templating\&. These variables are prefixed with \fIfacter_\fR and \'ohai_" so it\(cqs easy to tell their source\&. -.PP -\fBmetadata=\fR -.RS 4 -Optionally overrides the default JSON file location of /etc/ansible/setup\&. If used, also supply the metadata parameter to -\fItemplate\fR\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&. -.RE -.PP -\fBanything=\fR -.RS 4 -any other parameters can be named basically anything, and set a key=value pair in the JSON file for use in templating\&. -.RE -.SH "TEMPLATE" -.sp -Templates a file out to a remote server\&. Call the setup module prior to usage\&. -.PP -\fBsrc=\fR -.RS 4 -path of a Jinja2 formatted template on the local server -.RE -.PP -\fBdest\fR -.RS 4 -location to render the template on the remote server -.RE -.PP -\fBmetadata\fR -.RS 4 -location of a JSON file to use to supply template data\&. Default is /etc/ansible/setup which is the same as the default for the setup module\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&. -.RE -.sp -This module also returns md5sum information about the resultant file\&. -.SH "USER" -.sp -This module is in plan\&. -.SH "YUM" -.sp -This module is in plan\&. -.SH "WRITING YOUR OWN MODULES" -.sp -To write your own modules, simply follow the convention of those already available in /usr/share/ansible\&. Modules must return JSON but can be written in any language\&. To support change hooks, modules should return hashes, with a changed: True/False element at the top level\&. Modules can also choose to indicate a failure scenario by returning a top level \fIfailure\fR element with a True value\&. -.SH "AUTHOR" -.sp -Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&. -.SH "SEE ALSO" -.sp -\fBansible\fR(1) -.sp -\fBansible\-playbook\fR(5) -.sp -Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man5/ansible-playbook.5 b/docs/man/man5/ansible-playbook.5 deleted file mode 100644 index 3f0a02a6107..00000000000 --- a/docs/man/man5/ansible-playbook.5 +++ /dev/null @@ -1,66 +0,0 @@ -'\" t -.\" Title: ansible-modules -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 02/28/2012 -.\" Manual: System administration commands -.\" Source: Ansible-playbook 0.0.1 -.\" Language: English -.\" -.TH "ANSIBLE\-MODULES" "5" "02/28/2012" "Ansible\-playbook 0\&.0\&.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-playbook \- format and function of an ansible playbook file -.SH "DESCRIPTION" -.sp -Ansible ships with \fIansible\-playbook\fR, a tool for running playbooks\&. Playbooks can represent frequent tasks, desired system configurations, or deployment processes\&. -.SH "FORMAT" -.sp -Playbooks are written in YAML\&. -.SH "EXAMPLE" -.sp -see https://github\&.com/mpdehaan/ansible/blob/master/examples/playbook\&.yml -.SH "WHAT THE EXAMPLE MEANS" -.sp -Here\(cqs what the above example will do\&. -.sp -For all hosts in /etc/ansible/hosts (one host per line) that are named \fIwebserver\-anything\fR, first write a JSON file into /etc/ansible/setup on each remote system with the values max_clients and http_port\&. -.sp -Next, use a Jinja2 template locally residing at /srv/templates/httpd\&.j2 to write the Apache config file on each host to the path /etc/httpd\&.conf, using the previous values\&. -.sp -We\(cqll ensure that apache is running if stopped\&. -.sp -If and only if the config file changed, note that we need to restart apache at the end of the run, otherwise, don\(cqt bother because we already know it is running\&. -.SH "HIGH LEVEL EXPLANATION" -.sp -Playbooks are executed top down and can contain multiple references to patterns\&. For instance, a playbook could do something to all webservers, then do something to all database servers, then do something different to all webservers again\&. -.sp -For each pattern, the tasks in the \fItasks\fR list are executed in order for all hosts in the host file matching the pattern\&. -.sp -For each task, a name/action pair describes what the task is and what ansible module to use to accomplish the task, along with any arguments\&. Additional fields like \fIcomment:\fR can be added and will be ignored, so feel free to take notes in the file\&. -.sp -Most modules accept key=value format arguments\&. -.sp -Handlers are like tasks, but are conditionally executed\&. If a module reports a \fIchange\fR, it can notify one or more handler by name\&. If notified, it will run only for hosts that changed\&. -.SH "ERROR HANDLING" -.sp -If a host has a failure, the host will be ignored for the remainder of the playbook execution\&. -.SH "AUTHOR" -.sp -Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&. -.SH "SEE ALSO" -.sp -\fBansible\fR(1) -.sp -\fBansible\-playbook\fR(5) \- pending -.sp -Ansible home page: https://github\&.com/mpdehaan/ansible/