From 903d4771a199287e171db9f5239bdaee6dcd8ab0 Mon Sep 17 00:00:00 2001 From: Charles Chan Date: Fri, 25 Mar 2016 16:35:04 -0700 Subject: [PATCH] Improve documentation. --- docsite/rst/intro_adhoc.rst | 16 +++++++++------- docsite/rst/intro_configuration.rst | 12 ++++++------ docsite/rst/playbooks_intro.rst | 17 ++++++++--------- docsite/rst/playbooks_roles.rst | 11 +++++++---- 4 files changed, 30 insertions(+), 26 deletions(-) diff --git a/docsite/rst/intro_adhoc.rst b/docsite/rst/intro_adhoc.rst index 1d614bda7a0..a42a8cd2744 100644 --- a/docsite/rst/intro_adhoc.rst +++ b/docsite/rst/intro_adhoc.rst @@ -166,10 +166,10 @@ Ensure a package is not installed:: $ ansible webservers -m yum -a "name=acme state=absent" -Ansible has modules for managing packages under many platforms. If your package manager -does not have a module available for it, you can install -packages using the command module or (better!) contribute a module -for other package managers. Stop by the mailing list for info/details. +Ansible has modules for managing packages under many platforms. If there isn't +a module for your package manager, you can install packages using the +command module or (better!) contribute a module for your package manager. +Stop by the mailing list for info/details. .. _users_and_groups: @@ -223,8 +223,10 @@ Ensure a service is stopped:: Time Limited Background Operations `````````````````````````````````` -Long running operations can be backgrounded, and their status can be checked on -later. If you kick hosts and don't want to poll, it looks like this:: +Long running operations can be run in the background, and it is possible to +check their status later. For example, to execute ``long_running_operation` +asynchronously in the background, with a timeout of 3600 seconds (``-B``), +and without polling (-P):: $ ansible all -B 3600 -P 0 -a "/usr/bin/long_running_operation --do-stuff" @@ -238,7 +240,7 @@ Polling is built-in and looks like this:: $ ansible all -B 1800 -P 60 -a "/usr/bin/long_running_operation --do-stuff" -The above example says "run for 30 minutes max (``-B``: 30*60=1800), +The above example says "run for 30 minutes max (``-B`` 30*60=1800), poll for status (``-P``) every 60 seconds". Poll mode is smart so all jobs will be started before polling will begin on any machine. diff --git a/docsite/rst/intro_configuration.rst b/docsite/rst/intro_configuration.rst index 1ca71e210e0..029d0964814 100644 --- a/docsite/rst/intro_configuration.rst +++ b/docsite/rst/intro_configuration.rst @@ -184,12 +184,12 @@ command_warnings .. versionadded:: 1.8 -By default since Ansible 1.8, Ansible will warn when usage of the shell and -command module appear to be simplified by using a default Ansible module -instead. This can include reminders to use the 'git' module instead of -shell commands to execute 'git'. Using modules when possible over arbitrary -shell commands can lead to more reliable and consistent playbook runs, and -also easier to maintain playbooks:: +By default since Ansible 1.8, Ansible will issue a warning when the shell or +command module is used and the command appears to be similar to an existing +Ansible module. For example, this can include reminders to use the 'git' module +instead of shell commands to execute 'git'. Using modules when possible over +arbitrary shell commands can lead to more reliable and consistent playbook runs, +and also easier to maintain playbooks:: command_warnings = False diff --git a/docsite/rst/playbooks_intro.rst b/docsite/rst/playbooks_intro.rst index 7a5679ed63c..e891be659c1 100644 --- a/docsite/rst/playbooks_intro.rst +++ b/docsite/rst/playbooks_intro.rst @@ -73,10 +73,9 @@ For starters, here's a playbook that contains just one play:: - name: restart apache service: name=httpd state=restarted -We can also break task items out over multiple lines using the YAML dictionary -types to supply module arguments. This can be helpful when working with tasks -that have really long parameters or modules that take many parameters to keep -them well structured. Below is another version of the above example but using +When working with tasks that have really long parameters or modules that take +many parameters, you can break tasks items over multiple lines to improve the +structure. Below is another version of the above example but using YAML dictionaries to supply the modules with their ``key=value`` arguments.:: --- @@ -259,8 +258,8 @@ which is totally ok if the command is something like be used to make these modules also idempotent. Every task should have a ``name``, which is included in the output from -running the playbook. This is output for humans, so it is -nice to have reasonably good descriptions of each task step. If the name +running the playbook. This is human readable output, and so it is +useful to have provide good descriptions of each task step. If the name is not provided though, the string fed to 'action' will be used for output. @@ -365,9 +364,9 @@ The things listed in the ``notify`` section of a task are called handlers. Handlers are lists of tasks, not really any different from regular -tasks, that are referenced by a globally unique name. Handlers are -what notifiers notify. If nothing notifies a handler, it will not -run. Regardless of how many things notify a handler, it will run only +tasks, that are referenced by a globally unique name, and are notified +by notifiers. If nothing notifies a handler, it will not +run. Regardless of how many tasks notify a handler, it will run only once, after all of the tasks complete in a particular play. Here's an example handlers section:: diff --git a/docsite/rst/playbooks_roles.rst b/docsite/rst/playbooks_roles.rst index 980dce74158..7c56f4e7cd0 100644 --- a/docsite/rst/playbooks_roles.rst +++ b/docsite/rst/playbooks_roles.rst @@ -9,8 +9,10 @@ Introduction While it is possible to write a playbook in one very large file (and you might start out learning playbooks this way), eventually you'll want to reuse files and start to organize things. -At a basic level, including task files allows you to break up bits of configuration policy into smaller files. Task includes -pull in tasks from other files. Since handlers are tasks too, you can also include handler files from the 'handlers:' section. +At a basic level, including task files allows you to break up bits of +configuration policy into smaller files. Task includes pull in tasks from other +files. Since handlers are tasks too, you can also include handler files from +the 'handler' section. See :doc:`playbooks` if you need a review of these concepts. @@ -57,8 +59,9 @@ Include directives look like this, and can be mixed in with regular tasks in a p You can also pass variables into includes. We call this a 'parameterized include'. -For instance, if deploying multiple wordpress instances, I could -contain all of my wordpress tasks in a single wordpress.yml file, and use it like so:: +For instance, to deploy to multiple wordpress instances, I could +encapsulate all of my wordpress tasks in a single wordpress.yml file, and use +it like so:: tasks: - include: wordpress.yml wp_user=timmy