Merge pull request #5717 from nanobeep/devel

Minor documentation fixes.

docsite/rst/developing_inventory.rst

@@ -16,7 +16,7 @@ You can do this in any language.
 Script Conventions
 ``````````````````
 
-When the external node script is called with the single argument '--list', the script must return a JSON hash/dictionary of all the groups to be managed. Each group's value should be either a hash/dictionary containing a list of each host/IP, potential child groups, and potential group variables, or simply a list of host/IP addresses, like so::
+When the external node script is called with the single argument ``--list``, the script must return a JSON hash/dictionary of all the groups to be managed. Each group's value should be either a hash/dictionary containing a list of each host/IP, potential child groups, and potential group variables, or simply a list of host/IP addresses, like so::
 
     {
         "databases"   : {
@@ -41,7 +41,7 @@ When the external node script is called with the single argument '--list', the s
 
 Before version 1.0, each group could only have a list of hostnames/IP addresses, like the webservers, marietta, and 5points groups above.
 
-When called with the arguments '--host <hostname>' (where <hostname> is a host from above), the script must return either an empty JSON
+When called with the arguments ``--host <hostname>`` (where <hostname> is a host from above), the script must return either an empty JSON
 hash/dictionary, or a hash/dictionary of variables to make available to templates and playbooks.  Returning variables is optional,
 if the script does not wish to do this, returning an empty hash/dictionary is the way to go::
 
@@ -59,11 +59,11 @@ Tuning the External Inventory Script
 .. versionadded:: 1.3
 
 The stock inventory script system detailed above works for all versions of Ansible, but calling
-'--host' for every host can be rather expensive,  especially if it involves expensive API calls to
+``--host`` for every host can be rather expensive,  especially if it involves expensive API calls to
 a remote subsystem.  In Ansible
 1.3 or later, if the inventory script returns a top level element called "_meta", it is possible
 to return all of the host variables in one inventory script call.  When this meta element contains
-a value for "hostvars", the inventory script will not be invoked with "--host" for each host.  This
+a value for "hostvars", the inventory script will not be invoked with ``--host`` for each host.  This
 results in a significant performance increase for large numbers of hosts, and also makes client
 side caching easier to implement for the inventory script.
 

docsite/rst/glossary.rst

@@ -37,7 +37,7 @@ in the GitHub project perform custom logging, send email, or even play sound eff
 Check Mode
 ++++++++++
 
-Refers to running Ansible with the --check option, which does not make any changes on the remote systems, but only outputs the changes that
+Refers to running Ansible with the ``--check`` option, which does not make any changes on the remote systems, but only outputs the changes that
 might occur if the command ran without this flag.  This is analogous to so-called "dry run" modes in other systems, though the user should
 be warned that this does not take into account unexpected command failures or cascade effects (which is true of similar modes in other
 systems).  Use this to get an idea of what might happen, but it is not a substitute for a good staging environment.
@@ -62,8 +62,8 @@ discussed in the playbook documentation.
 Diff Mode
 +++++++++
 
-A --diff flag can be passed to Ansible to show how template files change when they are overwritten, or how they might change when used
-with --check mode.   These diffs come out in unified diff format.
+A ``--diff`` flag can be passed to Ansible to show how template files change when they are overwritten, or how they might change when used
+with ``--check`` mode.   These diffs come out in unified diff format.
 
 Facts
 +++++
@@ -93,7 +93,7 @@ self destruct after a set period of time.  This means the bus does not allow man
 Forks
 +++++
 
-Ansible talks to remote nodes in parallel and the level of parallelism can be set either by passing --forks, or editing the default in a configuration
+Ansible talks to remote nodes in parallel and the level of parallelism can be set either by passing ``--forks``, or editing the default in a configuration
 file.  The default is a very conservative 5 forks, though if you have a lot of RAM, you can easily set this to a value like 50 for increased
 parallelism.  
 
@@ -228,7 +228,7 @@ A collection of modules made available to /usr/bin/ansible or an Ansible playboo
 Limit Groups
 ++++++++++++
 
-By passing "--limit somegroup" to ansible or ansible-playbook, the commands can be limited to a subset of hosts.  For instance, 
+By passing ``--limit somegroup`` to ansible or ansible-playbook, the commands can be limited to a subset of hosts.  For instance, 
 this can be used to run a playbook that normally targets an entire set of servers to one particular server.
 
 Local Connection

docsite/rst/index.rst

@@ -9,7 +9,7 @@ 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.  
 
-Ansible's goals are foremost those of simplicity and maximum 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 (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans -- even those not familiar with the program.
+Ansible's goals are foremost those of simplicity and maximum ease of use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans -- even those not familiar with the program.
 
 We believe simplicity is relevant to all sizes of environments and design for busy users of all types -- whether this means developers, sysadmins, release engineers, IT managers, and everywhere in between. Ansible is appropriate for managing small setups with a handful of instances as well as enterprise environments with many thousands.
 

docsite/rst/intro_dynamic_inventory.rst

@@ -186,7 +186,7 @@ To see the complete list of variables available for an instance, run the script
     ./ec2.py --host ec2-12-12-12-12.compute-1.amazonaws.com
 
 Note that the AWS inventory script will cache results to avoid repeated API calls, and this cache setting is configurable in ec2.ini.  To
-explicitly clear the cache, you can run the ec2.py script with the '--refresh-cache' parameter.
+explicitly clear the cache, you can run the ec2.py script with the ``--refresh-cache`` parameter.
 
 .. _other_inventory_scripts:
 

docsite/rst/intro_getting_started.rst

@@ -26,16 +26,16 @@ Before we get started, it's important to understand how Ansible is communicating
 machines over SSH. 
 
 By default, Ansible 1.3 and later will try to use native 
-OpenSSH for remote communication  when possible.  This enables both ControlPersist (a performance feature), Kerberos, and options in ~/.ssh/config such as Jump Host setup.  When using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), however, the version of OpenSSH may be too old to support Control Persist. On these operating systems, Ansible will fallback into using a high-quality python implementation of
+OpenSSH for remote communication  when possible.  This enables both ControlPersist (a performance feature), Kerberos, and options in ~/.ssh/config such as Jump Host setup.  When using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), however, the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of
 OpenSSH called 'paramiko'.  If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform -- or engage 'accelerated mode' in Ansible.  See :doc:`playbooks_acceleration`.
 
 In Ansible 1.2 and before, the default was strictly paramiko and native SSH had to be explicitly selected with -c ssh or set in the configuration file.
 
 Occasionally you'll encounter a device that doesn't do SFTP. This is rare, but if talking with some remote devices that don't support SFTP, you can switch to SCP mode in :doc:`intro_configuration`.
 
-When speaking with remote machines, Ansible will by default assume you are using SSH keys -- which we encourage -- but passwords are fine too.  To enable password auth, supply the option --ask-pass where needed.  If using sudo features and when sudo requires a password, also supply --ask-sudo-pass as appropriate.
+When speaking with remote machines, Ansible will by default assume you are using SSH keys -- which we encourage -- but passwords are fine too.  To enable password auth, supply the option ``--ask-pass`` where needed.  If using sudo features and when sudo requires a password, also supply ``--ask-sudo-pass`` as appropriate.
 
-While it may be common sense, it is worth sharing: Any management system benefits from being run near your machines you are being managed. If running in a cloud, consider running Ansible from a machine inside that cloud.  It will work better than on the open
+While it may be common sense, it is worth sharing: Any management system benefits from being run near the machines being managed. If running in a cloud, consider running Ansible from a machine inside that cloud.  It will work better than on the open
 intranet in most cases.
 
 As an advanced topic, Ansible doesn't just have to connect remotely over SSH.  The transports are pluggable, and there are options for managing things locally, as well as managing chroot, lxc, and jail containers.  A mode called 'ansible-pull' can also invert the system and have systems 'phone home' via scheduled git checkouts to pull configuration directives from a central repository.
@@ -64,7 +64,7 @@ do:
     $ ssh-agent bash
     $ ssh-add ~/.ssh/id_rsa
 
-(Depending on your setup, you may wish to use 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:
 
@@ -127,7 +127,7 @@ Also note that host key checking in paramiko mode is reasonably slow, therefore
 .. _a_note_about_logging:
 
 Ansible will log some information about module arguments on the remote system in the remote syslog.  To enable basic
-logging on the control machine see `intro_config` document and set the 'log_path' configuration file setting.  Enterprise users may also be interested in `AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx>`_.  AWX provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API.
+logging on the control machine see :doc:`intro_configuration` document and set the 'log_path' configuration file setting.  Enterprise users may also be interested in `AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx>`_.  AWX provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API.
 
 .. seealso::
 

docsite/rst/intro_installation.rst

@@ -19,7 +19,7 @@ Basics / What Will Be Installed
 
 Ansible by default manages machines over the SSH protocol.
 
-Once ansible is installed, it will not add a database, and there will be no daemons to start or keep running.  You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point.  When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version.
+Once Ansible is installed, it will not add a database, and there will be no daemons to start or keep running.  You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point.  When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version.
 
 .. _what_version:
 
@@ -46,7 +46,7 @@ information about running from source.  It's not necessary to install the progra
 Control Machine Requirements
 ````````````````````````````
 
-Currently Ansible can be from any machine with Python 2.6 installed (Windows isn't supported for the control machine).
+Currently Ansible can be run from any machine with Python 2.6 installed (Windows isn't supported for the control machine).
 
 This includes Red Hat, Debian, CentOS, OS X, any of the BSDs, and so on.
   
@@ -76,10 +76,10 @@ On the managed nodes, you only need Python 2.4 or later, but if you are are runn
 
 .. note::
 
-   Python 3 is a slightly different language than Python 2 and most python programs (including
+   Python 3 is a slightly different language than Python 2 and most Python programs (including
    Ansible) are not switching over yet.  However, some Linux distributions (Gentoo, Arch) may not have a 
    Python 2.X interpreter installed by default.  On those systems, you should install one, and set
-   the 'ansible_python_interpreter' variable in inventory (see :doc:`intro_inventory`) to point at your 2.X python.  Distributions
+   the 'ansible_python_interpreter' variable in inventory (see :doc:`intro_inventory`) to point at your 2.X Python.  Distributions
    like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu all have a 2.X interpreter installed
    by default and this does not apply to those distributions.  This is also true of nearly all
    Unix systems.  If you need to bootstrap these remote systems by installing Python 2.X, 
@@ -148,7 +148,7 @@ RPMs are available from yum for `EPEL
 Fedora distributions. 
 
 Ansible itself can manage earlier operating
-systems that contain python 2.4 or higher (so also EL5).
+systems that contain Python 2.4 or higher (so also EL5).
 
 Fedora users can install Ansible directly, though if you are using RHEL or CentOS and have not already done so, `configure EPEL <http://fedoraproject.org/wiki/EPEL>`_
    
@@ -210,11 +210,9 @@ Readers that use virtualenv can also install Ansible under virtualenv, though we
 Tarballs of Tagged Releases
 +++++++++++++++++++++++++++
 
-Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout?  Tarballs of releases are available on the ansibleworks.com page.
+Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout?  Tarballs of releases are available on the `Ansible/downloads <http://ansibleworks.com/releases>`_ page.
 
-* `Ansible/downloads <http://ansibleworks.com/releases>`_
-
-These releases are also tagged in the git repository with the release version.
+These releases are also tagged in the `git repository <https://github.com/ansible/ansible/releases>`_ with the release version.
 
 .. seealso::
 

docsite/rst/intro_patterns.rst

@@ -72,7 +72,7 @@ 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::
+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::
 
     ansible-playbook site.yml --limit datacenter2
 

docsite/rst/playbooks_best_practices.rst

@@ -359,8 +359,8 @@ Keep It Simple
 
 When you can do something simply, do something simply.  Do not reach
 to use every feature of Ansible together, all at once.  Use what works
-for you.  For example, you will probably not need 'vars',
-'vars_files', 'vars_prompt' and '--extra-vars' all at once,
+for you.  For example, you will probably not need ``vars``,
+``vars_files``, ``vars_prompt`` and ``--extra-vars`` all at once,
 while also using an external inventory file.
 
 .. _version_control:

docsite/rst/playbooks_checkmode.rst

@@ -5,7 +5,7 @@ Check Mode ("Dry Run")
 
 .. contents:: Topics
 
-When ansible-playbook is executed with --check it will not make any changes on remote systems.  Instead, any module
+When ansible-playbook is executed with ``--check`` it will not make any changes on remote systems.  Instead, any module
 instrumented to support 'check mode' (which contains most of the primary core modules, but it is not required that all modules do
 this) will report what changes they would have made rather than making them.  Other modules that do not support check mode will also take no action, but just will not report what changes they might have made.
 
@@ -42,13 +42,13 @@ true.
 
 .. _diff_mode:
 
-Showing Differences with --diff
-```````````````````````````````
+Showing Differences with ``--diff``
+```````````````````````````````````
 
 .. versionadded:: 1.1
 
-The --diff option to ansible-playbook works great with --check (detailed above) but can also be used by itself.  When this flag is supplied, if any templated files on the remote system are changed, and the ansible-playbook CLI will report back
-the textual changes made to the file (or, if used with --check, the changes that would have been made).  Since the diff
+The ``--diff`` option to ansible-playbook works great with ``--check`` (detailed above) but can also be used by itself.  When this flag is supplied, if any templated files on the remote system are changed, and the ansible-playbook CLI will report back
+the textual changes made to the file (or, if used with ``--check``, the changes that would have been made).  Since the diff
 feature produces a large amount of output, it is best used when checking a single host at a time, like so::
 
     ansible-playbook foo.yml --check --diff --limit foo.example.com

docsite/rst/playbooks_intro.rst

@@ -348,7 +348,7 @@ run ansible-playbook against that content.
 
 Assuming you load balance your checkout location, ansible-pull scales essentially infinitely.
 
-Run 'ansible-pull --help' for details.
+Run ``ansible-pull --help`` for details.
 
 There's also a `clever playbook <https://github.com/ansible/ansible-examples/blob/master/language_features/ansible_pull.yml>`_ available to using ansible in push mode to configure ansible-pull via a crontab!
 
@@ -362,7 +362,7 @@ and how they performed.   General failures and fatal "unreachable" communication
 kept separate in the counts.
 
 If you ever want to see detailed output from successful modules as well as unsuccessful ones,
-use the '--verbose' flag.  This is available in Ansible 0.5 and later.
+use the ``--verbose`` flag.  This is available in Ansible 0.5 and later.
 
 Ansible playbook output is vastly upgraded if the cowsay
 package is installed.  Try it!

docsite/rst/playbooks_variables.rst

@@ -500,9 +500,9 @@ Similarly, the hostname as the system reports it is::
     {{ ansible_hostname }}
 
 
-Facts are frequently used in conditionals (see `playbook_conditionals`) and also in templates.
+Facts are frequently used in conditionals (see :doc:`playbook_conditionals`) and also in templates.
 
-Facts can be also used to create dynamic groups of hosts that match particular criteria, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter.
+Facts can be also used to create dynamic groups of hosts that match particular criteria, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the :doc:`playbook_conditionals` chapter.
 
 .. _disabling_facts:
 
@@ -848,7 +848,7 @@ roles aren't you?  Hint hint.
 
 Ok, so if you are writing a redistributable role with reasonable defaults, put those in the 'roles/x/defaults/main.yml' file.  This means
 the role will bring along a default value but ANYTHING in Ansible will override it.  It's just a default.  That's why it says "defaults" :)
-See `intro_roles` for more info about this::
+See :doc:`playbooks_roles` for more info about this::
 
     ---
     # file: roles/x/defaults/main.yml