Merge branch 'docs_examples' of git://github.com/jpmens/ansible into standardize_docs

docsite/latest/rst/moduledev.rst

@@ -363,12 +363,9 @@ Include it in your module file like this::
     module: modulename
     short_description: This is a sentence describing the module
     # ... snip ...
-    examples:
-        - code: modulename opt1=arg1 opt2=arg2
-          description: Optional words describing this example
     '''
 
-The ``description``, ``notes`` and ``description`` within ``examples``
+The ``description``, and ``notes`` 
 support formatting in some of the output formats (e.g. ``rst``, ``man``).
 These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()``
 for URL, module, italic, and constant-width respectively. It is suggested
@@ -376,7 +373,7 @@ to use ``C()`` for file and option names, and ``I()`` when referencing
 parameters; module names should be specifies as ``M(module)``.
 
 Examples (which typically contain colons, quotes, etc.) are difficult
-to format with YAML, so these can (alternatively, or additionally) be
+to format with YAML, so these must be
 written in plain text in an ``EXAMPLES`` string within the module
 like this::
 
@@ -385,7 +382,7 @@ like this::
     '''
 
 The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
-``EXAMPLES`` blob after any existing ``examples`` you may have in the
+``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the
 YAML ``DOCUMENTATION`` string.
 
 Building & Testing

docsite/latest/rst/playbooks.rst

@@ -36,8 +36,8 @@ Playbook Language Example
 Playbooks are expressed in YAML format and have a minimum of syntax.
 Each playbook is composed of one or more 'plays' in a list.
 
-The goal of a play is map a group of hosts to some well defined roles, represented by
-things ansible called tasks.  At the basic level, a task is nothing more than a call
+The goal of a play is to map a group of hosts to some well defined roles, represented by
+things ansible calls tasks.  At a basic level, a task is nothing more than a call
 to an ansible module, which you should have learned about in earlier chapters.
 
 By composing a playbook of multiple 'plays', it is possible to