From c193f774c2ab2e81c36315f81c663f24281f114e Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael.dehaan@gmail.com>
Date: Thu, 10 May 2012 01:33:19 -0400
Subject: [PATCH] Doc custom facts

---
 rst/moduledev.rst | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/rst/moduledev.rst b/rst/moduledev.rst
index 8eb767c020a..5fc6652a0c1 100644
--- a/rst/moduledev.rst
+++ b/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
 ```````````````