Add toctrees to pages in the docs that did not have them.

docsite/latest/rst/YAMLSyntax.rst

@@ -1,6 +1,9 @@
 YAML Syntax
 ===========
 
+.. contents::
+   :depth: 2
+
 This page provides a basic overview of correct YAML syntax, which is how Ansible
 playbooks (our configuration management language) are expressed.  
 

docsite/latest/rst/developing_inventory.rst

@@ -1,6 +1,9 @@
 Developing Dynamic Inventory Sources
 ====================================
 
+.. contents:: `Table of contents`
+   :depth: 2
+
 As described in `intro_inventory_dynamic`, ansible can pull inventory information from dynamic sources, including cloud sources.
 
 How do we write a new one?

docsite/latest/rst/developing_plugins.rst

@@ -1,6 +1,9 @@
 Developing Plugins
 ==================
 
+.. contents::
+   :depth: 2
+
 Ansible is pluggable in a lot of other ways seperate from inventory scripts and callbacks.  Many of these features are there to cover
 fringe use cases and are infrequently needed, and others are pluggable simply because they are there to implement core features
 in ansible and were most convient to be made pluggable.

docsite/latest/rst/glossary.rst

@@ -1,6 +1,9 @@
 Glossary
 ========
 
+.. contents::
+   :depth: 2
+
 The following is a list (and re-explanation) of term definitions used elsewhere in the Ansible documentation.
 
 Consult the documentation home page for the full documentation and to see the terms in context, but this should be a good resource

docsite/latest/rst/index.rst

@@ -1,28 +1,33 @@
 
-
 Ansible Documentation
-`````````````````````
+=====================
 
-Welcome to the Ansible documentation.  
+About Ansible
+`````````````
 
-Ansible is an IT automation tool.  It can configure systems, deploy software, and orchestrate more advanced IT orchestration
+Welcome to the Ansible documentation!
+
+Ansible is an IT automation tool.  It can configure systems, deploy software, and orchestrate more advanced IT tasks
 such as continuous deployments or zero downtime rolling updates.
 
-Ansibe's goals are foremost those of simplicity and ease of use. It also has a strong focus on security and reliability, featuring
+Ansible's goals are foremost those of simplicity and ease of use. It also has a strong focus on security and reliability, featuring
-a minimum of moving parts, usage of Open SSH for transport, and a language that is designed around auditability by humans -- even those
+a minimum of moving parts, usage of Open SSH for transport (with an accelerated socket mode as an alternative that uses SSH for key exchange), and a language that is designed around auditability by humans -- even those not familiar with the program.
-not familiar with the program.
 
-This documentation covers the current released version of Ansible (1.3.X) and also some development version features (1.4).  For recent features, in each section, the version of Ansible where the feature is added is indicated.  Ansible produces a new major release approximately
+Ansible manages machines in an agentless manner --  the intent here is to make things more reliable and 
-every 2 months.
+there are no additional open ports.   This also means there is never a question of how to
+upgrade the management software with the management software, or the problem of not being able to manage remote nodes because
+management daemons are not yet installed or not currently running.  As OpenSSH is one of the most peer reviewed open source components, the security exposure of using the tool is therefore also greatly reduced.  Ansible is decentralized, and relies on your existing OS credentials to control access to remote machines, rather than just who can edit configuration recipes in source control.
 
-Before we dive into playbooks, configuration management, deployment, and orchestration, we'll learn how to get Ansible installed and some
+You may be interested in reading about `some notable Ansible users <http://www.ansibleworks.com/users/>`_.
-basic information.  We'll go over how to execute ad-hoc commands in parallel across your nodes using /usr/bin/ansible.  We'll also see
+
-what sort of modules are available in Ansible's core (though you can also write your own, which we'll also show later).
+This documentation covers the current released version of Ansible (1.3.X) and also some development version features (1.4).  For recent features, in each section, the version of Ansible where the feature is added is indicated.  Ansible produces a new major release approximately every 2 months.  The core project moves somewhat conservatively, valuing simplicity in language design and setup, while the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release.
+
+Before we dive into playbooks, configuration management, deployment, and orchestration, we'll learn how to get Ansible installed and some basic concepts.  We'll go over how to execute ad-hoc commands in parallel across your nodes using /usr/bin/ansible.  We'll also see what sort of modules are available in Ansible's core (though you can also write your own, which we'll also show later).
 
 .. _an_introduction:
 
-An Introduction
+The Basics
-```````````````
+``````````
 
 .. toctree::
    :maxdepth: 1
@@ -34,12 +39,23 @@ An Introduction
    intro_patterns
    intro_adhoc
    intro_configuration
+
+Modules
+```````
+
+Ansible modules are resources that are distributed to remote nodes to make them perform particular tasks or match a particular
+state.  Ansible follows a "batteries included" philosophy, so you have a lot of great modules for all manner of
+IT tasks in the core distribution.  This means modules are well up-to-date and you don't have to hunt for an implementation
+that will work on your platform.  You may think of the module library as a toolbox full of useful system management tools, 
+and playbooks as the instructions for buildilng something using those tools.
+
+.. toctree:
    modules
 
 .. _overview:
 
-Overview
+Architecture Diagram
-````````
+````````````````````
 
 .. image:: http://www.ansibleworks.com/wp-content/uploads/2013/06/ANSIBLE_DIAGRAM.jpg
    :alt: ansible architecture diagram
@@ -48,20 +64,21 @@ Overview
 
 .. _introduction_to_playbooks:
 
-An Introduction to Playbooks
+Playbooks
-````````````````````````````
+`````````
 
-Playbooks are Ansible's configuration, deployment, and orchestration language.  They can describe a policy you want your remote systems
+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.
-to enforce, or a set of steps in a general IT process.
 
 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.  
 
-There's no need to learn everything at once.  You can start small and pick up more features
+While there's a lot of information here, there's no need to learn everything at once.  You can start small and pick up more features
 over time as you need them.  
 
 Playbooks are designed to be human-readable and are developed in a basic text language.  There are multiple
 ways to organize playbooks and the files they include, and we'll offer up some suggestions on that and making the most out of Ansible.
 
+It is recommended to look at `Example Playbooks <https://github.com/ansible/ansible-examples>`_ while reading along with the playbook documentation.  These illustrate best practices as well as how to put many of the various concepts together.
+
 .. toctree::
    :maxdepth: 1
 
@@ -72,29 +89,14 @@ ways to organize playbooks and the files they include, and we'll offer up some s
    playbooks_loops
    playbooks_best_practices
 
-It is recommended to look at `Example Playbooks <https://github.com/ansible/ansible-examples>`_ while reading along with the playbook documentation.  These illustrate best practices as well as how to put many of the various concepts together.
-
-.. ansibleworks_awx:
-
-Upgrading the Ansible Experience: AnsibleWorks AWX
-``````````````````````````````````````````````````
-
-`AnsibleWorks <http://ansibleworks.com>`_, who also sponsors the Ansible community, also produces 'AWX', which is a web-based tool that makes Ansible even more easy to use for IT teams of all kinds.  It's designed to be the hub for all of your automation tasks.
-
-AWX allows you to control access to who can access what, even allowing sharing of SSH credentials without someone being able to transfer those credentials.  Inventory can be graphically managed or synced with a widde variety of cloud sources.  It logs all of your jobs, integrates well with LDAP, and has an amazing browseable REST API.
-
-Find out more about AWX features and how to download it on the `AWX webpage <http://ansibleworks.com/ansibleworks-awx>`_.  AWX
-is free for usage for up to 10 nodes, and comes bundled with amazing support from AnsibleWorks.  As you would expect, AWX is 
-installed using Ansible playbooks!
-
 .. _advanced_topics_in_playbooks:
 
-Advanced Topics In Playbooks
+Special Topics In Playbooks
-````````````````````````````
+```````````````````````````
 
 Here are some playbook features that not everyone may need to learn, but can be quite useful for particular applications. 
-Browsing these topics is recommended as you may find some useful tips here, but feel free to learn Ansible first and adopt
+Browsing these topics is recommended as you may find some useful tips here, but feel free to learn the basics of Ansible first 
-these only if they seem relevant or useful to your environment.
+and adopt these only if they seem relevant or useful to your environment.
 
 .. toctree::
    :maxdepth: 1
@@ -109,23 +111,33 @@ these only if they seem relevant or useful to your environment.
    playbooks_prompts
    playbooks_tags
 
+.. _ansibleworks_awx:
+
+AnsibleWorks AWX
+````````````````
+
+`AnsibleWorks <http://ansibleworks.com>`_, who also sponsors the Ansible community, also produces 'AWX', which is a web-based solution that makes Ansible even more easy to use for IT teams of all kinds.  It's designed to be the hub for all of your automation tasks.
+
+AWX allows you to control access to who can access what, even allowing sharing of SSH credentials without someone being able to transfer those credentials.  Inventory can be graphically managed or synced with a widde variety of cloud sources.  It logs all of your jobs, integrates well with LDAP, and has an amazing browseable REST API.  Command line tools are available for easy integration
+with Jenkins as well.  
+
+Find out more about AWX features and how to download it on the `AWX webpage <http://ansibleworks.com/ansibleworks-awx>`_.  AWX
+is free for usage for up to 10 nodes, and comes bundled with amazing support from AnsibleWorks.  As you would expect, AWX is
+installed using Ansible playbooks!
+
 .. _detailed_guides:    
 
 Detailed Guides
 ```````````````
 
-This section is new and evolving.  The idea here is explore particular use cases in greater depth and provide a more "top down" explanation
+This section is new and evolving.  The idea here is explore particular use cases in greater depth and provide a more "top down" explanation of some basic features::
-of some basic features.  
-
-A chance to dive into some more topics in depth:
 
 .. toctree::
    :maxdepth: 1
 
    guide_aws
 
-Pending topics may include: Vagrant, Docker, Jenkins, Rackspace Cloud, Google Compute Engine, Linode/Digital Ocean, Continous Deployment, 
+Pending topics may include: Vagrant, Docker, Jenkins, Rackspace Cloud, Google Compute Engine, Linode/Digital Ocean, Continous Deployment, and more.
-and more.
 
 .. _community_information:
 
@@ -133,8 +145,7 @@ Community Information
 `````````````````````
 
 Ansible is an open source project designed to bring together developers and administrators of all kinds to collaborate on building
-IT automation solutions that work well for them.   Should you wish to get more involved -- whether in terms of just asking a question, helping
+IT automation solutions that work well for them.   Should you wish to get more involved -- whether in terms of just asking a question, helping other users, introducing new people to Ansible, or helping with the software or documentation, we welcome your contributions to the project.
-other users, introducing new people to Ansible, or helping with the software or documentation, we welcome your contributions to the project.
 
 `Ways to interact <https://github.com/ansible/ansible/blob/devel/CONTRIBUTING.md>`_
 
@@ -143,8 +154,7 @@ other users, introducing new people to Ansible, or helping with the software or
 Developer Information
 `````````````````````
 
-Learn how to build modules of your own in any language, and also how to extend ansible through several kinds of plugins. Explore Ansible's Python API and write Python plugins to integrate
+Learn how to build modules of your own in any language, and also how to extend ansible through several kinds of plugins. Explore Ansible's Python API and write Python plugins to integrate with other solutions in your environment.
-with other solutions in your environment.
 
 .. toctree::
    :maxdepth: 1
@@ -154,7 +164,6 @@ with other solutions in your environment.
    developing_modules
    developing_plugins
 
-
 Developers will also likely be interested in the fully-discoverable `REST API <http://ansibleworks.com/ansibleworks-awx>`_ that is part of AnsibleWorks AWX.  It's great for embedding Ansible in all manner of applications.
 
 .. _misc:
@@ -162,6 +171,8 @@ Developers will also likely be interested in the fully-discoverable `REST API <h
 Miscellaneous
 `````````````
 
+Some additional topics you may be interested in:
+
 .. toctree::
    :maxdepth: 1
 

docsite/latest/rst/intro_dynamic_inventory.rst

@@ -14,6 +14,10 @@ Ansible easily supports all of these options via an external inventory system.
 
 For information about writing your own, see :doc:`developing_inventory`.
 
+.. contents::
+   :depth: 2
+
+
 .. _cobbler_example:
 
 Example: The Cobbler External Inventory Script

docsite/latest/rst/intro_patterns.rst

@@ -1,5 +1,8 @@
 .. _patterns:
 
+.. contents::
+   :depth: 2
+
 Patterns
 ++++++++
 

docsite/latest/rst/playbooks_acceleration.rst

@@ -1,6 +1,9 @@
 Accelerated Mode
 ================
 
+.. contents::
+   :depth: 2
+
 .. versionadded:: 1.3
 
 While SSH using the ControlPersist feature is quite fast and scalable, there is a certain amount of overhead involved in

docsite/latest/rst/playbooks_async.rst

@@ -1,6 +1,9 @@
 Asynchronous Actions and Polling
 ================================
 
+.. contents::
+   :depth: 2
+
 By default tasks in playbooks block, meaning the connections stay open
 until the task is done on each node.  This may not always be desirable, or you may
 be running operations that take longer than the SSH timeout.

docsite/latest/rst/playbooks_checkmode.rst

@@ -1,6 +1,9 @@
 Check Mode ("Dry Run")
 ======================
 
+.. contents::
+   :depth: 2
+
 .. versionadded:: 1.1
 
 When ansible-playbook is executed with --check it will not make any changes on remote systems.  Instead, any module

docsite/latest/rst/playbooks_conditionals.rst

@@ -1,6 +1,9 @@
 Conditionals
 ============
 
+.. contents::
+   :depth: 2
+
 Often the result of a play may depend on the value of a variable, fact (something learned about the remote system), 
 or previous task result.  In some cases, the values of variables may depend on other variables.  
 Further, additional groups can be created to manage hosts based on

docsite/latest/rst/playbooks_delegation.rst

@@ -1,6 +1,9 @@
 Delegation, Rolling Updates, and Local Actions
 ==============================================
 
+.. contents::
+   :depth: 2
+
 Being designed for multi-tier deployments since the beginning, Ansible is great at doing things on one host on behalf of another, or doing local steps with reference to some remote hosts.
 
 This in particular this is very applicable when setting up continuous deployment infrastructure or zero downtime rolling updates, where you might be talking with load balancers or monitoring systems.

docsite/latest/rst/playbooks_environment.rst

@@ -1,6 +1,9 @@
 Setting the Environment (and Working With Proxies)
 ==================================================
 
+.. contents::
+   :depth: 2
+
 .. versionadded:: 1.1
 
 It is quite possible that you may need to get package updates through a proxy, or even get some package

docsite/latest/rst/playbooks_error_handling.rst

@@ -1,6 +1,9 @@
 Error Handling In Playbooks
 ===========================
 
+.. contents::
+   :depth: 2
+
 Ansible normally has defaults that make sure to check the return codes of commands and modules and
 it fails fast -- forcing an error to be dealt with unless you decide otherwise.
 y

docsite/latest/rst/playbooks_lookups.rst

@@ -1,6 +1,9 @@
 Using Lookups
 =============
 
+.. contents::
+   :depth: 2
+
 Lookup plugins allow access of data in Ansible from outside sources.  This can include the filesystem
 but also external datastores.  These values are then made available using the standard templating system
 in Ansible, and are typically used to load variables or templates with information from those systems.

docsite/latest/rst/playbooks_loops.rst

@@ -1,6 +1,9 @@
 Loops
 =====
 
+.. contents::
+   :depth: 2
+
 All about how to use loops in playbooks.
 
 .. _standard_loops:

docsite/latest/rst/playbooks_prompts.rst

@@ -1,6 +1,9 @@
 Prompts
 =======
 
+.. contents::
+   :depth: 2
+
 You may wish to prompt the user for certain input, and can
 do so with the similarly named 'vars_prompt' section.  
 

docsite/latest/rst/playbooks_tags.rst

@@ -1,6 +1,9 @@
 Tags
 ====
 
+.. contents::
+   :depth: 2
+
 If you have a large playbook it may become useful to be able to run a
 specific part of the configuration without running the whole playbook.