Doc custom facts

rst/moduledev.rst

@@ -166,8 +166,32 @@ Let's test that module::
 
 This should return something like::
 
-    {"changed": true, "time": "2012-03-14 12:23:00.000307"}
+    {"changed": True, "time": "2012-03-14 12:23:00.000307"}
-
+
+
+Module Provided 'Facts'
+```````````````````````
+
+The 'setup' module that ships with Ansible provides many variables about a system that can be used in playbooks
+and templates.  However, it's possible to also add your own facts without modifying the system module.  To do
+this, just have the module return a `ansible_facts` key, like so, along with other return data.  This requires
+Ansible 0.4 and later::
+
+    {
+        "changed" : True,
+        "rc" : 5,
+        "ansible_facts" : {
+            "leptons" : 5000
+            "colors" : {
+                "red"   : "FF0000",
+                "white" : "FFFFFF"
+            }
+        }
+    }
+
+These 'facts' will be available to all statements called after that module (but not before) in the playbook.
+A good idea might be make a module called 'site_facts' and always call it at the top of each playbook, though
+we're always open to improving the selection of core facts in Ansible as well.
 
 Common Pitfalls
 ```````````````