From 26c141e96e46af2d705a7f7b60ddcba66f5d9e00 Mon Sep 17 00:00:00 2001 From: John Callender Date: Wed, 2 May 2012 06:53:29 -0700 Subject: [PATCH] Issue #84: Doc tweaks for modules, moduledev, and playbooks --- rst/moduledev.rst | 8 +++++--- rst/modules.rst | 6 ++++-- rst/playbooks.rst | 6 ++++++ 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/rst/moduledev.rst b/rst/moduledev.rst index 28f84036fd..8eb767c020 100644 --- a/rst/moduledev.rst +++ b/rst/moduledev.rst @@ -188,11 +188,13 @@ You should also never do this in a module:: Because the output is supposed to be valid JSON. Except that's not quite true, but we'll get to that later. -Further, modules must not output anything on stderr, even if the JSON returned -out stdout is valid. This is due to the internals of our SSH library, more or less. +Modules must not output anything on standard error, because the system will merge +standard out with standard error and prevent the JSON from parsing. Capturing standard +error and returning it as a variable in the JSON on standard out is fine, and is, in fact, +how the command module is implemented. If a module returns stderr or otherwise fails to produce valid JSON, the actual output -will still be shown in Ansible, however, but the command will not succeed. +will still be shown in Ansible, but the command will not succeed. Always use the hacking/test-module script when developing modules and it will warn you about these kind of things. diff --git a/rst/modules.rst b/rst/modules.rst index 09d039de96..c8a3492f60 100644 --- a/rst/modules.rst +++ b/rst/modules.rst @@ -431,7 +431,9 @@ on your remote systems. *variablename*: - * Arbitrary names can be used as variables. 'variablename' can be basically anything, and sets a ``key=value`` pair in the JSON file for use in templating. +* Arbitrary variable names, which must be a mix of alphanumeric characters and +underscores, can also be defined. Setting a variable creates a +``key=value`` pair in the JSON file for use in templating. Example action from Ansible :doc:`playbooks`:: @@ -451,7 +453,7 @@ shell The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the command module -but runs the command through the shell rather than directly. +but runs the command through the user's configured shell on the remote node. The given command will be executed on all selected nodes. diff --git a/rst/playbooks.rst b/rst/playbooks.rst index 0ae6d69c28..ff510affe5 100644 --- a/rst/playbooks.rst +++ b/rst/playbooks.rst @@ -501,6 +501,12 @@ To save some typing, repeated tasks can be written in short-hand like so:: - testuser1 - testuser2 +The above would be the equivalent of:: + + - name: add user testuser1 + action: user name=testuser1 state=present groups=wheel + - name: add user testuser2 + action: user name=testuser2 state=present groups=wheel Asynchronous Actions and Polling ++++++++++++++++++++++++++++++++