Add DOCUMENTATION for module documentation.

docsite/DOCUMENTATION.yaml

@@ -0,0 +1 @@
+../examples/DOCUMENTATION.yaml

docsite/rst/moduledev.rst

@@ -310,6 +310,72 @@ If you're writing a module in Python or Ruby or whatever, though, returning
 JSON is probably the simplest way to go.
 
 
+Documenting Your Module
+```````````````````````
+
+All modules included in the CORE distribution must have a
+``DOCUMENTATION`` string. This string MUST be a valid YAML document
+which conforms to the schema defined below. You may find it easier to
+start writing your ``DOCUMENTATION`` string in an editor with YAML
+syntax highlighting before you include it in your Python file.
+
+Example
++++++++
+
+Here's a correctly formatted YAML document we could use for a
+``DOCUMENTATION`` string:
+
+.. literalinclude:: ../DOCUMENTATION.yaml
+
+This is available in the 'examples/' directory of the of the Ansible
+github repository. You can copy it into your module and use it as a
+starting point when writing your own docs.
+
+Include it in your module file like this::
+
+    #!/usr/bin/env python
+    # Copyright header....
+
+    DOCUMENTATION = '''
+    ---
+    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
+    '''
+
+Building & Testing
+++++++++++++++++++
+
+Put your completed module file into the 'library' directory and then
+run the command: ``make webdocs``. The new 'modules.html' file will be
+built and appear in the 'docsite/' directory.
+
+You can also test-build your docs one-by-one using the
+``module_formatter.py`` script:
+
+.. code-block:: bash
+
+   $ ./hacking/module_formatter.py -t man -M library/ -m git > ansible-git.1
+   $ man ./ansible-git.1
+
+This will build a manpage for the git module, and look in the
+'library/' directory for the module source. To see all the other
+output formats available:
+
+.. code-block:: bash
+
+   $ ./hacking/module_formatter.py -t --help
+
+
+.. tip::
+
+   If you're having a problem with the syntax of your YAML you can
+   validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
+
+
 Sharing Your Module
 ```````````````````
 
@@ -343,4 +409,3 @@ the program.   Stop by the mailing list to inquire about requirements.
        Questions? Help? Ideas?  Stop by the list on Google Groups
    `irc.freenode.net <http://irc.freenode.net>`_
        #ansible IRC chat channel
-

examples/DOCUMENTATION.yaml

@@ -0,0 +1,33 @@
+---
+# If a key doesn't apply to your module (ex: choices, default, or
+# aliases) you can use the word 'null', or an empty list, [], where
+# appropriate.
+module: modulename
+short_description: This is a sentence describing the module
+description:
+    - Longer description of the module
+    - You might include instructions
+version_added: 0.X
+author: Your AWESOME name here
+notes:
+    - Other things consumers of your module should know
+requirements:
+    - list of required things
+    - like the factor package
+    - or a specic platform
+options:
+# One or more of the following
+    option_name:
+        description:
+            - Words go here
+            - that describe
+            - this option
+        required: true or false
+        default: a string or the word null
+        choices: [list, of, choices]
+        aliases: [list, of, aliases]
+        version_added: 0.X
+examples:
+# One or more of the following:
+    - code: modulename opt1=arg1 opt2=arg2
+      description: Optional words describing this example