From 267ada33eb309e3b34983a231b2c46b00d350027 Mon Sep 17 00:00:00 2001
From: Jan-Piet Mens <jpmens@gmail.com>
Date: Fri, 28 Sep 2012 21:55:49 +0200
Subject: [PATCH] Module DOCUMENTATION: assemble, authorized_key, command, copy
plus a small fix in rst.j2 template
manpages generated & checked
modules.html generated & checked
---
assemble | 43 +++++++++++++++++++++++++++++++++++++++++++
authorized_key | 31 +++++++++++++++++++++++++++++++
command | 41 +++++++++++++++++++++++++++++++++++++++++
copy | 38 ++++++++++++++++++++++++++++++++++++++
4 files changed, 153 insertions(+)
diff --git a/assemble b/assemble
index d038b714950..5539552348c 100755
--- a/assemble
+++ b/assemble
@@ -23,6 +23,49 @@ import os.path
import shutil
import tempfile
+DOCUMENTATION = '''
+---
+module: assemble
+short_description: Assembles a configuration file from fragments
+description:
+ - Assembles a configuration file from fragments. Often a particular
+ program will take a single configuration file and does not support a
+ C(conf.d) style structure where it is easy to build up the configuration
+ from multiple sources. Assemble will take a directory of files that have
+ already been transferred to the system, and concatenate them together to
+ produce a destination file. Files are assembled in string sorting order.
+ Puppet calls this idea I(fragments).
+version_added: "0.5"
+options:
+ src:
+ description:
+ - An already existing directory full of source files.
+ required: true
+ default: null
+ aliases: []
+ dest:
+ description:
+ - A file to create using the concatenation of all of the source files.
+ required: true
+ default: null
+ backup:
+ description:
+ - Create a backup file (if C(yes)) including the timestamp information so
+ you can get the original file back if you somehow clobbered it
+ incorrectly.
+ required: false
+ choices: [ "yes", "no" ]
+ default: "no"
+ others:
+ description:
+ - all arguments accepted by the M(file) module also work here
+ required: false
+examples:
+ - code: assemble src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
+ description: "Example from Ansible Playbooks"
+author: Stephen Fromm
+'''
+
# ===========================================
# Support methods
diff --git a/authorized_key b/authorized_key
index 8ecd542f8df..1353459530b 100755
--- a/authorized_key
+++ b/authorized_key
@@ -21,6 +21,37 @@ You should have received a copy of the GNU General Public License
along with Ansible. If not, see <http://www.gnu.org/licenses/>.
"""
+DOCUMENTATION = '''
+---
+module: authorized_key
+short_description: Adds or removes an authorized key for a user from a remote host.
+description:
+ - Adds or removes an authorized key for a user from a remote host.
+version_added: "0.5"
+options:
+ user:
+ description:
+ - Name of the user who should have access to the remote host
+ required: true
+ default: null
+ aliases: []
+ key:
+ description:
+ - the SSH public key, as a string
+ required: true
+ default: null
+ state:
+ description:
+ - whether the given key should or should not be in the file
+ required: false
+ choices: [ "present", "absent" ]
+ default: "present"
+examples:
+ - code: authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"
+ description: "Example from Ansible Playbooks"
+author: Brad Olson
+'''
+
# Makes sure the public key line is present or absent in the user's .ssh/authorized_keys.
#
# Arguments
diff --git a/command b/command
index 585ebabd7b3..753aefe5ed4 100755
--- a/command
+++ b/command
@@ -25,6 +25,47 @@ import traceback
import shlex
import os
+DOCUMENTATION = '''
+---
+module: command
+short_description: Executes a command on a remote node
+description:
+ - The command module takes the command name followed by a list of arguments, space delimited.
+ - The given command will be executed on all selected nodes. It will not be
+ processed through the shell, so variables like C($HOME) and operations
+ like C("<"), C(">"), C("|"), and C("&") will not work. As such, all
+ paths to commands must be fully qualified
+options:
+ free_form:
+ description:
+ - the command module takes a free form command to run
+ required: true
+ default: null
+ aliases: []
+ creates:
+ description:
+ - a filename, when it already exists, this step will B(not) be run.
+ required: no
+ default: null
+ chdir:
+ description:
+ - cd into this directory before running the command
+ version_added: "0.6"
+ required: false
+ default: null
+examples:
+ - code: command /sbin/shutdown -t now
+ description: "Example from Ansible Playbooks"
+ - code: command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
+ description: "I(creates) and I(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this."
+notes:
+ - If you want to run a command through the shell (say you are using C(<),
+ C(>), C(|), etc), you actually want the M(shell) module instead. The
+ M(command) module is much more secure as it's not affected by the user's
+ environment.
+author: Michael DeHaan
+'''
+
def main():
# the command module is the one ansible module that does not take key=value args
diff --git a/copy b/copy
index de5ebcf4097..c92bcbdc3f8 100755
--- a/copy
+++ b/copy
@@ -22,6 +22,44 @@ import os
import shutil
import time
+DOCUMENTATION = '''
+---
+module: copy
+short_description: Copies files to remote locations.
+description:
+ - The M(copy) module copies a file on the local box to remote locations.
+options:
+ src:
+ description:
+ - Local path to a file to copy to the remote server; can be absolute or relative.
+ required: true
+ default: null
+ aliases: []
+ dest:
+ description:
+ - Remote absolute path where the file should be copied to.
+ required: true
+ default: null
+ backup:
+ description:
+ - Create a backup file including the timestamp information so you can get
+ the original file back if you somehow clobbered it incorrectly.
+ version_added: "0.7"
+ required: false
+ choices: [ "yes", "no" ]
+ default: "no"
+ others:
+ description:
+ - all arguments accepted by the M(file) module also work here
+ required: false
+examples:
+ - code: copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
+ description: "Example from Ansible Playbooks"
+ - code: copy src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes
+ description: "Copy a new C(ntp.conf) file into place, backing up the original if it differs from the copied version"
+author: Michael DeHaan
+'''
+
def main():
module = AnsibleModule(