From 60e0410298d76e6d882dceb46a1d543bb1ac7535 Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Wed, 19 Sep 2012 16:09:26 +0200 Subject: [PATCH] Tweak DOCUMENTATION YAML as per latest 991 --- library/file | 33 +++++++++++++++++++++++++++++++++ library/get_url | 32 ++++++++++++++++++-------------- library/raw | 24 ++++++++++++------------ library/setup | 28 ++++++++++++++-------------- 4 files changed, 77 insertions(+), 40 deletions(-) diff --git a/library/file b/library/file index 6927bac3c9..e1ca84b738 100755 --- a/library/file +++ b/library/file @@ -28,6 +28,39 @@ try: except ImportError: HAVE_SELINUX=False +DOCUMENTATION = ''' +--- +module: file +short_description: Sets attributes of files +description: + - Sets attributes of files, symlinks, and directories, or removes + files/symlinks/directories. Many other modules support the same options as + the file module - including M(copy), M(template), and M(assmeble). +version_added: "0.1" +options: + - dest: + description: + - defines the file being managed, unless when used with I(state=link), and then sets the destination to create a symbolic link to using I(src) + required: true + default: [] + aliases: [] + - state: + description: + - If directory, all immediate subdirectories will be created if they do not exist. If I(file), the file will NOT be created if it does not exist, see the M(copy) or M(template) module if you want that behavior. If I(link), the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked. + required: false + default: file + choices: [ file, link, directory, absent ] + - mode: + description: + - mode the file or directory should be, such as 0644 as would be fed to I(chmod). English modes like B(g+x) are not yet supported +examples: + - code: file path=/etc/foo.conf owner=foo group=foo mode=0644 + description: Example from Ansible Playbooks +notes: + - See also M(copy), M(template), M(assemble) +requirements: [ ] +''' + def add_path_info(kwargs): path = kwargs['path'] if os.path.exists(path): diff --git a/library/get_url b/library/get_url index 15e8caa438..d3ac2bcccc 100755 --- a/library/get_url +++ b/library/get_url @@ -28,39 +28,43 @@ 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. +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 + 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. + description: + - absolute path of where to download the file to. + - If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, I(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. + description: + - if C(yes), will download the file every time and replace the + file if the contents change. if C(no), the file will only be downloaded if + the destination does not exist. Generally should be C(yes) only for small + local files. prior to 0.6, acts if C(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 + description: + - all arguments accepted by the M(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. +notes: + - This module doesn't support proxies or passwords. + - Also see the M(template) module. # informational: requirements for nodes requirements: [ urllib2, urlparse ] ''' diff --git a/library/raw b/library/raw index af9ec64ac3..ea36198e7e 100755 --- a/library/raw +++ b/library/raw @@ -3,18 +3,18 @@ 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 +short_description: Executes a low-down and dirty SSH command +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 M(shell) or M(command) module is much more appropriate. Arguments + given to M(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 36106c6ecd..8749448397 100755 --- a/library/setup +++ b/library/setup @@ -30,20 +30,20 @@ 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. +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 C(/usr/bin/ansible) to check what variables are + available to a host. Ansible provides many I(facts) about the system, + automatically. +notes: + - More ansible facts will be added with successive releases. If I(facter) or + I(ohai) are installed, variables from these programs will also be snapshotted + into the JSON file for usage in templating. These variables are prefixed + with C(facter_) and C(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 I(facter) and I(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.