Merge pull request #1127 from jpmens/m-docs1

Module DOCUMENTATION: assemble, authorized_key, command, copy

hacking/templates/rst.j2

@@ -44,7 +44,7 @@
 .. raw:: html
 
 {% for example in examples %}
-    <p>@{ example['description'] }@</p>
+    {% if example['description'] %}<p>@{ example['description'] | html_ify }@</p>{% endif %}
     <p><pre>
     @{ example['code'] }@</pre></p>
 {% endfor %}

library/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
 

library/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

library/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

library/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(