Merge pull request #11637 from bcoca/moar_docs

Moar docs

docsite/rst/become.rst

@@ -49,7 +49,7 @@ New command line options
 --ask-become-pass
     ask for privilege escalation password
 
--b, --become
+--become,-b
     run operations with become (no password implied)
 
 --become-method=BECOME_METHOD

docsite/rst/developing_plugins.rst

@@ -21,7 +21,7 @@ Carrier Pigeon?) it's as simple as copying the format of one of the existing mod
 directory.   The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
 'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later.  Previous versions did not support 'smart'.
 
-More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/plugins/connections <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connections`_ and figure things out pretty easily.
+More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/plugins/connections <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connections>`_ and figure things out pretty easily.
 
 .. _developing_lookup_plugins:
 

docsite/rst/guides.rst

@@ -11,7 +11,6 @@ This section is new and evolving.  The idea here is explore particular use cases
    guide_gce
    guide_vagrant
    guide_rolling_upgrade
-   test_strategies
 
 Pending topics may include: Docker, Jenkins, Google Compute Engine, Linode/DigitalOcean, Continuous Deployment, and more.
 

docsite/rst/intro_configuration.rst

@@ -144,6 +144,27 @@ different locations::
 
 Most users will not need to use this feature.  See :doc:`developing_plugins` for more details
 
+.. _stdout_callback:
+
+stdout_callback
+===============
+
+.. versionadded:: 2.0
+
+This setting allows you to override the default stdout callback for ansible-playbook.
+
+.. _callback_whitelist:
+
+callback_whitelist
+==================
+
+.. versionadded:: 2.0
+
+Now ansible ships with all included callback plugins ready to use but they are disabled by default,
+this setting lets you enable a list of additional callbacks, this cannot change or override the
+default stdout callback, use :ref:`stdout_callback` for that.
+
+
 .. _command_warnings:
 
 command_warnings
@@ -285,9 +306,10 @@ gathering
 
 New in 1.6, the 'gathering' setting controls the default policy of facts gathering (variables discovered about remote systems).
 
-The value 'implicit' is the default, meaning facts will be gathered per play unless 'gather_facts: False' is set in the play.  The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play.
+The value 'implicit' is the default, which means that the fact cache will be ignored and facts will be gathered per play unless 'gather_facts: False' is set.
-
+The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play.
-The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run.  This option can be useful for those wishing to save fact gathering time.
+The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run.
+This option can be useful for those wishing to save fact gathering time. Both 'smart' and 'explicit' will use the fact cache.
 
 hash_behaviour
 ==============
@@ -801,3 +823,19 @@ If enabled, this setting allows multiple private keys to be uploaded to the daem
 
 New clients first connect to the target node over SSH to upload the key, which is done via a local socket file, so they must have the same access as the user that launched the daemon originally.
 
+.. _selinux_settings:
+
+Selinux Specific Settings
+-------------------------
+
+These are settings that control SELinux interactions.
+
+
+special_context_filesystems
+===========================
+
+.. versionadded:: 1.9
+
+This is a list of file systems that require special treatment when dealing with security context.
+The normal behaviour is for operations to copy the existing context or use the user default, this changes it to use a file system dependent context.
+The default list is: nfs,vboxsf,fuse,ramfs

docsite/rst/modules.rst

@@ -2,48 +2,20 @@ About Modules
 =============
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
 
-.. _modules_intro:
+   modules_intro
+   modules_core
+   modules_extra
+   common_return_values
 
-Introduction
-````````````
 
 Ansible ships with a number of modules (called the 'module library')
 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
+Users can also write their own modules. These modules can control system resources,
-handle executing system commands.
+like services, packages, or files (anything really), or handle executing system commands.
 
-Let's review how we execute three different modules from the command line::
-
-    ansible webservers -m service -a "name=httpd state=started"
-    ansible webservers -m ping
-    ansible webservers -m command -a "/sbin/reboot -t now"
-
-Each module supports taking arguments.  Nearly all modules take ``key=value``
-arguments, space delimited.  Some modules take no arguments, and the command/shell modules simply 
-take the string of the command you want to run.
-
-From playbooks, Ansible modules are executed in a very similar way::
-
-    - name: reboot the servers
-      action: command /sbin/reboot -t now
-
-Which can be abbreviated to::
-
-    - name: reboot the servers
-      command: /sbin/reboot -t now
-
-All modules technically return JSON format data, though if you are using the command line or playbooks, you don't really need to know much about
-that.  If you're writing your own module, you care, and this means you do not have to write modules in any particular language -- you get to choose.
-
-Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made.  When using Ansible
-playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks.
-
-Documentation for each module can be accessed from the command line with the ansible-doc tool::
-
-    ansible-doc yum
 
 .. seealso::
 
@@ -59,4 +31,3 @@ Documentation for each module can be accessed from the command line with the ans
        Questions? Help? Ideas?  Stop by the list on Google Groups
    `irc.freenode.net <http://irc.freenode.net>`_
        #ansible IRC chat channel
-

docsite/rst/modules_core.rst

@@ -0,0 +1,13 @@
+Core Modules
+------------
+
+These are modules that the core ansible team maintains and will always ship with ansible itself.
+They will also receive slightly higher priority for all requests than those in the "extras" repos.
+
+The source of these modules is hosted on GitHub in the `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ repo.
+
+If you believe you have found a bug in a core module and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ to see if a bug has already been filed.  If not, we would be grateful if you would file one.
+
+Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net.   Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
+
+Documentation updates for these modules can also be edited directly in the module itself and by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.

docsite/rst/modules_extra.rst

@@ -0,0 +1,22 @@
+Extras Modules
+--------------
+
+These modules are currently shipped with Ansible, but might be shipped separately in the future. They are also mostly maintained by the community.
+Non-core modules are still fully usable, but may receive slightly lower response rates for issues and pull requests.
+
+Popular "extras" modules may be promoted to core modules over time.
+
+This source for these modules is hosted on GitHub in the `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ repo.
+
+If you believe you have found a bug in an extras module and are already running the latest stable or development version of Ansible,
+first look in the `issue tracker at github.com/ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_
+o see if a bug has already been filed.  If not, we would be grateful if you would file one.
+
+Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_
+or on Ansible's "#ansible" channel, located on irc.freenode.net.
+Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
+
+Documentation updates for this module can also be edited directly in the module and by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
+
+For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`developing_test_pr` and :doc:`developing_modules`.
+

docsite/rst/modules_intro.rst

@@ -0,0 +1,64 @@
+Introduction
+============
+
+Modules (also referred to as "task plugins" or "library plugins") are the ones that do
+the actual work in ansible, they are what gets executed in each playbook task.
+But you can also run a single one using the 'ansible' command.
+
+Let's review how we execute three different modules from the command line::
+
+    ansible webservers -m service -a "name=httpd state=started"
+    ansible webservers -m ping
+    ansible webservers -m command -a "/sbin/reboot -t now"
+
+Each module supports taking arguments.  Nearly all modules take ``key=value``
+arguments, space delimited.  Some modules take no arguments, and the command/shell modules simply
+take the string of the command you want to run.
+
+From playbooks, Ansible modules are executed in a very similar way::
+
+    - name: reboot the servers
+      action: command /sbin/reboot -t now
+
+Which can be abbreviated to::
+
+    - name: reboot the servers
+      command: /sbin/reboot -t now
+
+Another way to pass arguments to a module is using yaml syntax also called 'complex args' ::
+
+    - name: restart webserver
+      service:
+        name: httpd
+        state: restarted
+
+All modules technically return JSON format data, though if you are using the command line or playbooks, you don't really need to know much about
+that.  If you're writing your own module, you care, and this means you do not have to write modules in any particular language -- you get to choose.
+
+Modules strive to be `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made.  When using Ansible
+playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks.
+
+Documentation for each module can be accessed from the command line with the ansible-doc tool::
+
+    ansible-doc yum
+
+A list of all installed modules is also available::
+
+    ansible-doc -l
+
+
+.. seealso::
+
+   :doc:`intro_adhoc`
+       Examples of using modules in /usr/bin/ansible
+   :doc:`playbooks`
+       Examples of using modules with /usr/bin/ansible-playbook
+   :doc:`developing_modules`
+       How to write your own modules
+   :doc:`developing_api`
+       Examples of using modules with the Python API
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+

docsite/rst/playbooks.rst

@@ -24,6 +24,8 @@ It is recommended to look at `Example Playbooks <https://github.com/ansible/ansi
    playbooks_filters
    playbooks_conditionals
    playbooks_loops
+   playbooks_blocks
+   playbooks_strategies
    playbooks_best_practices
 
 

docsite/rst/playbooks_blocks.rst

@@ -0,0 +1,72 @@
+Blocks
+======
+
+In 2.0 we added a block feature to allow for logical grouping of tasks and even
+in play error handling. Most of what you can apply to a single task can be applied
+at the block level, which also makes it much easier to set data or directives common
+to the tasks.
+
+
+Example::
+
+    tasks:
+      - block:
+
+          - yum: name={{ item }} state=installed
+            with_items:
+              - httpd
+              - memcached
+
+          - template: src=templates/src.j2 dest=/etc/foo.conf
+
+          - service: name=bar state=started enabled=True
+
+        when: ansible_distribution == 'CentOS'
+        become: true
+        become_user: root
+
+In the example above the 3 tasks will be executed only when the block's when condition is met and enables
+privilege escalation for all the enclosed tasks.
+
+
+.. _block_error_handling:
+
+Error Handling
+``````````````
+
+About Blocks
+Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.::
+
+  tasks:
+   - block:
+       - debug: msg='i execute normally'
+       - command: /bin/false
+       - debug: msg='i never execute, cause ERROR!'
+     rescue:
+       - debug: msg='I caught an error'
+       - command: /bin/false
+       - debug: msg='I also never execute :-('
+     always:
+       - debug: msg="this always executes"
+
+
+The tasks in the ``block`` would execute normally, if there is any error the ``rescue`` section would get executed
+with whatever you need to do to recover from the previous error. The ``always`` section runs no matter what previous
+error did or did not occur in the ``block`` and ``rescue`` sections.
+
+
+
+.. seealso::
+
+   :doc:`playbooks`
+       An introduction to playbooks
+   :doc:`playbooks_roles`
+       Playbook organization by roles
+   `User Mailing List <http://groups.google.com/group/ansible-devel>`_
+       Have a question?  Stop by the google group!
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+
+
+
+

docsite/rst/playbooks_strategies.rst

@@ -0,0 +1,39 @@
+Strategies
+===========
+
+In 2.0 we added a new way to control play execution, ``strategy``, by default plays will
+still run as they used to, with what we call the ``linear`` strategy. All hosts will run each
+task before any host starts the next task, using the number of forks (default 5) to parallelize.
+
+The ``serial`` directive can 'batch' this behaviour to a subset of the hosts, which then run to
+completion of the play before the next 'batch' starts.
+
+A second ``strategy`` ships with ansible ``free``, which allows each host to run until the end of
+the play as fast as it can.::
+
+    - hosts: all
+      strategy: free
+      tasks:
+      ...
+
+
+.. _strategy_plugins:
+
+Strategy Plugins
+`````````````````
+
+The strategies are implelented via a new type of plugin, this means that in the future new
+execution types can be added, either locally by users or to Ansible itself by
+a code contribution.
+
+.. seealso::
+
+   :doc:`playbooks`
+       An introduction to playbooks
+   :doc:`playbooks_roles`
+       Playbook organization by roles
+   `User Mailing List <http://groups.google.com/group/ansible-devel>`_
+       Have a question?  Stop by the google group!
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
+

hacking/templates/rst.j2

@@ -175,31 +175,14 @@ Notes
 This is a Core Module
 ---------------------
 
-The source of this module is hosted on GitHub in the `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ repo.
+For more information on what this means please read :doc:`modules_core`
-
-If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ to see if a bug has already been filed.  If not, we would be grateful if you would file one.
-
-Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net.   Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
-
-Documentation updates for this module can also be edited directly by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
-
-This is a "core" ansible module, which means it will receive slightly higher priority for all requests than those in the "extras" repos.
 
     {% else %}
 
 This is an Extras Module
 ------------------------
 
-This source of this module is hosted on GitHub in the `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ repo.
+For more information on what this means please read :doc:`modules_extra`
-
-If you believe you have found a bug in this module, and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ to see if a bug has already been filed.  If not, we would be grateful if you would file one.
-
-Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net.   Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
-
-Documentation updates for this module can also be edited directly by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
-
-Note that this module is designated a "extras" module.  Non-core modules are still fully usable, but may receive slightly lower response rates for issues and pull requests.
-Popular "extras" modules may be promoted to core modules over time.
 
     {% endif %}
 {% endif %}