ansible/ansible — pull request #2120 by jpmens (2013-02-18 14:38:15+00:00)
Title: Add support for additional EXAMPLES string in Ansible modules

Writing up examples in the YAML DOCUMENTATION can (admittedly) be a bit of a pain due to the escaping of colons, etc.

We've created an additional, and optional variable which can be defined in modules, called `EXAMPLES`. This is meant to be a plain-text (i.e. unparsed) string in which to document examples for playbooks. Note, that this can be used in addition to or instead of _examples_ in the DOCUMENTATION string.

Support of this is now added and tested for

* ansible-doc (1)
* hacking/module_formatter
* rST template
* Markdown template
* man page template

The following fictitious example uses both:

```python
examples:
- code: "get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440"
description: "Example from Ansible Playbooks"
notes:
- This module doesn't yet support configuration for proxies.
# informational: requirements for nodes
requirements: [ urllib2, urlparse ]
author: Jan-Piet Mens
'''

EXAMPLES = '''
- action: get_url
url="http://colon:one@two.three/name='Jane Jolie' and:
something other '" with some quotes
- template: src=/tmp/me.to:oo dest=/tmp/other--file
'''
```

When run through the module formatter, the result looks like this (on the Web pages)

![jmbp-491](https://f.cloud.github.com/assets/60706/167492/c5afb3a0-79d8-11e2-9262-2ef70268bc85.png)