Merge pull request #4607 and fix merge conflicts for documentation fixes.

docsite/rst/index.rst

@@ -1,4 +1,3 @@
-
 Ansible Documentation
 =====================
 
@@ -70,7 +69,7 @@ Playbooks
 
 Playbooks are Ansible's configuration, deployment, and orchestration language.  They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process.
 
-If Ansible modules are your the tools in your workshop, playbooks are your design plans.
+If Ansible modules are the tools in your workshop, playbooks are your design plans.
 
 At a basic level, playbooks can be used to manage configurations of and deployments to remote machines.  At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way.  
 

docsite/rst/intro_adhoc.rst

@@ -1,4 +1,3 @@
-
 Introduction To Ad-Hoc Commands
 ===============================
 
@@ -100,7 +99,7 @@ Using the :ref:`shell` module looks like this::
     $ ansible raleigh -m shell -a 'echo $TERM'
 
 When running any command with the Ansible *ad hoc* CLI (as opposed to
-:doc:`playbooks`), pay particular attention to shell quoting rules, so
+:doc:`Playbooks <playbooks>`), pay particular attention to shell quoting rules, so
 the local shell doesn't eat a variable before it gets passed to Ansible.
 For example, using double vs single quotes in the above example would
 evaluate the variable on the box you were on.
@@ -243,7 +242,7 @@ very quickly. After the time limit (in seconds) runs out (``-B``), the process o
 the remote nodes will be terminated.
 
 Typically you'll be only be backgrounding long-running
-shell commands or software upgrades only.  Backgrounding the copy module does not do a background file transfer.  :doc:`playbooks` also support polling, and have a simplified syntax for this.
+shell commands or software upgrades only.  Backgrounding the copy module does not do a background file transfer.  :doc:`Playbooks <playbooks>` also support polling, and have a simplified syntax for this.
 
 .. _checking_facts:
 
@@ -257,36 +256,7 @@ system.  These can be used to implement conditional execution of tasks but also
 
 Its also possible to filter this output to just export certain facts, see the "setup" module documentation for details.
 
-Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`playbooks`. 
+Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`Playbooks <playbooks>`. 
-
-.. _limiting_hosts:
-
-Limiting Selected Hosts
-```````````````````````
-
-What hosts you select to manage can be additionally constrained by using the '--limit' parameter or
-by using 'batch' (or 'range') selectors.
-
-As mentioned above, patterns can be strung together to select hosts in more than one group::
-
-    $ ansible webservers:dbservers -m command -a "/bin/foo xyz"
-
-This is an "or" condition.  If you want to further constrain the selection, use --limit, which
-also works with ``ansible-playbook``::
-
-    $ ansible webservers:dbservers -m command -a "/bin/foo xyz" --limit region
-
-Assuming version 0.9 or later, as with other host patterns, values to limit can be separated with ";", ":", or ",".
-
-Now let's talk about range selection.   Suppose you have 1000 servers in group 'datacenter', but only want to target one at a time.  This is also easy::
-
-    $ ansible webservers[0-99] -m command -a "/bin/foo xyz"
-    $ ansible webservers[100-199] -m command -a "/bin/foo xyz"
-
-This will select the first 100, then the second 100, host entries in the webservers group.  (It does not matter
-what their names or IP addresses are).
-
-Both of these methods can be used at the same time, and ranges can also be passed to the --limit parameter.
 
 .. seealso::
 

docsite/rst/intro_configuration.rst

@@ -1,4 +1,3 @@
-
 The Ansible Configuration File
 ++++++++++++++++++++++++++++++
 
@@ -7,7 +6,7 @@ The Ansible Configuration File
 Certain things in Ansible are adjustable in a configuration file.  In general, the stock configuration is probably
 right for most users, but that doesn't mean you might not want to change them.
 
-The mechanism for doing this is the "ansible.cfg" file, which is looked for in the following locations:
+The mechanism for doing this is the "ansible.cfg" file, which is looked for in the following locations::
 
     * /etc/ansible/ansible.cfg
     * ~/.ansible.cfg
@@ -30,8 +29,7 @@ as a ".rpmnew" file (or other) as appropriate in the case of updates.
 If you have installed from pip or from source, however, you may want to create this file in order to override
 default settings in Ansible.
 
-You may wish to consult the `ansible.cfg in source control <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>` for
+You may wish to consult the `ansible.cfg in source control <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_ for all of the possible latest values.
-all of the possible latest values.
 
 .. _environmental_configuration:
 
@@ -283,7 +281,7 @@ log_path
 ========
 
 If present and configured in ansible.cfg, Ansible will log information about executions at the designated location.  Be sure
-the user running Ansible has permissions on the logfile.
+the user running Ansible has permissions on the logfile::
 
     log_path=/var/log/ansible.log
 

docsite/rst/intro_dynamic_inventory.rst

@@ -33,12 +33,9 @@ been referred to as a 'lightweight CMDB' by some admins.   This particular scrip
 using Cobbler's XMLRPC API.
 
 To tie Ansible's inventory to Cobbler (optional), copy `this script <https://raw.github.com/ansible/ansible/devel/plugins/inventory/cobbler.py>`_ to /etc/ansible and `chmod +x` the file.  cobblerd will now need
-to be running when you are using Ansible.  
+to be running when you are using Ansible and you'll need to use Ansible's  ``-i`` command line option (e.g. ``-i /etc/ansible/cobbler.py``).
 
-When running Ansible, to use this inventory, execute ansible with the "-i /etc/ansible/cobbler.py" parameter.
+First test the script by running ``/etc/ansible/cobbler.py`` directly.   You should see some JSON data output, but it may not have anything in it just yet.
-
-First test the script by running `/etc/ansible/cobbler.py` directly.   You should see some JSON data output, but it may not have
-anything in it just yet.
 
 Let's explore what this does.  In cobbler, assume a scenario somewhat like the following::
 

docsite/rst/intro_getting_started.rst

@@ -65,7 +65,7 @@ do:
     $ ssh-agent bash
     $ ssh-add ~/.ssh/id_rsa
 
-(Depending on your setup, you may wish to ansible's --private-key option to specify a pem file instead)
+(Depending on your setup, you may wish to use Ansible's --private-key option to specify a pem file instead)
 
 Now ping all your nodes:
 
@@ -119,6 +119,8 @@ If you wish to disable this behavior and understand the implications, you can do
 
 Alternatively this can be set by an environment variable:
 
+.. code-block:: bash
+
     $ export ANSIBLE_HOST_KEY_CHECKING=False
 
 Also note that host key checking in paramiko mode is reasonably slow, therefore switching to 'ssh' is also recommended when using this feature.

docsite/rst/intro_patterns.rst

@@ -73,9 +73,32 @@ Most people don't specify patterns as regular expressions, but you can.  Just st
 
     ~(web|db).*\.example\.com
 
-While we're jumping a bit ahead, additionally, you can add an exclusion criteria just by supplying the "--limit" flag to /usr/bin/ansible or /usr/bin/ansible-playbook::
+Limiting Selected Hosts
+```````````````````````
 
-    ansible-playbook site.yml --limit datacenter2
+What hosts you select to manage can be additionally constrained by using the '--limit' parameter or
+by using 'batch' (or 'range') selectors.
+
+As mentioned above, patterns can be strung together to select hosts in more than one group::
+
+    $ ansible webservers:dbservers -m command -a "/bin/foo xyz"
+
+This is an "or" condition.  If you want to further constrain the selection, use --limit, which
+also works with ``ansible-playbook``::
+
+    $ ansible webservers:dbservers -m command -a "/bin/foo xyz" --limit region
+
+Assuming version 0.9 or later, as with other host patterns, values to limit can be separated with ";", ":", or ",".
+
+Now let's talk about range selection.   Suppose you have 1000 servers in group 'datacenter', but only want to target one at a time.  This is also easy::
+
+    $ ansible webservers[0-99] -m command -a "/bin/foo xyz"
+    $ ansible webservers[100-199] -m command -a "/bin/foo xyz"
+
+This will select the first 100, then the second 100, host entries in the webservers group.  (It does not matter
+what their names or IP addresses are).
+
+Both of these methods can be used at the same time, and ranges can also be passed to the --limit parameter.
 
 Easy enough.  See :doc:`intro_adhoc` and then :doc:`playbooks` for how to apply this knowledge.
 

docsite/rst/modules.rst

@@ -11,7 +11,7 @@ Introduction
 
 
 Ansible ships with a number of modules (called the 'module library')
-that can be executed directly on remote hosts or through :doc:`playbooks`.
+that can be executed directly on remote hosts or through :doc:`Playbooks <playbooks>`.
 Users can also write their own modules.   These modules can control system
 resources, like services, packages, or files (anything really), or
 handle executing system commands.