From e041c2e2cd69e15b299e55906b1f10cffc1f1e4f Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Mon, 17 Sep 2012 15:11:04 +0200 Subject: [PATCH] First attempt at standardizing DOCUMENTATION string (new DICT) --- library/get_url | 41 +++++++++++++++++++++++++++++++++++++++++ library/raw | 20 ++++++++++++++++++++ library/setup | 23 +++++++++++++++++++++++ 3 files changed, 84 insertions(+) diff --git a/library/get_url b/library/get_url index 37a713d3226..15e8caa4389 100755 --- a/library/get_url +++ b/library/get_url @@ -24,6 +24,47 @@ import shutil import datetime import tempfile +DOCUMENTATION = ''' +--- +module: get_url +short_description: Downloads files from HTTP, HTTPS, or FTP to node +description: > + Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote + server must have direct access to the remote resource. +version_added: "0.6" +options: + - url: + description: HTTP, HTTPS, or FTP URL + required: true + default: null + aliases: [] + - dest: + description: absolute path of where to download the file to. If dest is a + directory, the basename of the file on the remote server will be used. If + a directory, thirsty=yes must also be set. + required: true + default: null + - thirsty: + description: if yes, will download the file every time and replace the + file if the contents change. if no, the file will only be downloaded if + the destination does not exist. Generally should be 'yes' only for small + local files. prior to 0.6, acts if 'yes' by default. + version_added: "0.7" + required: false + choices: [ "yes", "no" ] + default: "no" + - others: + description: all arguments accepted by the file module also work here + required: false +examples: + - code: get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440 + description: Obtain and install config file +notes: > + This module doesn't support proxies or passwords. +# informational: requirements for nodes +requirements: [ urllib2, urlparse ] +''' + HAS_URLLIB2=True try: import urllib2 diff --git a/library/raw b/library/raw index 9132aeebbed..af9ec64ac32 100755 --- a/library/raw +++ b/library/raw @@ -1 +1,21 @@ # this is a virtual module that is entirely implemented server side + +DOCUMENTATION = ''' +--- +module: raw +short_description: Executes a low-down and dirty SSH command, not going through the module subsystem. +description: > + Executes a low-down and dirty SSH command, not going through the module + subsystem. This is useful and should only be done in two cases. The first + case is installing python-simplejson on older (python 2.4 and before) + hosts that need it as a dependency to run modules, since nearly all core + modules require it. Another is speaking to any devices such as routers + that do not have any Python installed. In any other case, using the + 'shell' or 'command' module is much more appropriate. Arguments given to + 'raw' are run directly through the configured remote shell and only output + is returned. There is no error detection or change handler support for + this module +examples: + - code: ansible newhost.example.com -m raw -a "yum -y install python-simplejson" + description: Example from /usr/bin/ansible to bootstrap a legacy python 2.4 host +''' diff --git a/library/setup b/library/setup index 5499c2f8576..b448961e4c1 100755 --- a/library/setup +++ b/library/setup @@ -26,6 +26,29 @@ import re import socket import struct +DOCUMENTATION = ''' +--- +module: setup +short_description: Gathers facts about remote hosts +description: > + This module is automatically called by playbooks to gather useful + variables about remote hosts that can be used in playbooks. It can also be + executed directly by /usr/bin/ansible to check what variables are + available to a host. Ansible provides many 'facts' about the system, + automatically. +notes: > + More ansible facts will be added with successive releases. 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 facter_ and ohai_ so it's easy to tell their source. All variables are + bubbled up to the caller. Using the ansible facts and choosing to not + install facter and ohai means you can avoid ruby-dependencies on your + remote systems. +examples: + - code: ansible all -m setup -tree /tmp/facts + description: Obtain facts from all hosts and store them indexed by hostname at /tmp/facts. +''' + try: import selinux HAVE_SELINUX=True