diff --git a/example/execnet/popen_read_multiple.py b/example/execnet/popen_read_multiple.py
new file mode 100644
index 000000000..0f5e2a515
--- /dev/null
+++ b/example/execnet/popen_read_multiple.py
@@ -0,0 +1,37 @@
+"""
+example
+
+reading results from possibly blocking code running in sub processes. 
+"""
+import py
+
+NUM_PROCESSES = 5
+
+channels = []
+for i in range(NUM_PROCESSES):
+    gw = py.execnet.PopenGateway() # or use SSH or socket gateways 
+    channel = gw.remote_exec("""
+        import time
+        secs = channel.receive()
+        time.sleep(secs)
+        channel.send("waited %d secs" % secs)
+    """)
+    channels.append(channel)
+    print "*** instantiated subprocess", gw
+
+mc = py.execnet.MultiChannel(channels)
+queue = mc.make_receive_queue()
+
+print "***", "verifying that timeout on receiving results from blocked subprocesses works"
+try:
+    queue.get(timeout=1.0) 
+except Exception:
+    pass
+
+print "*** sending subprocesses some data to have them unblock"
+mc.send_each(1) 
+
+print "*** receiving results asynchronously"
+for i in range(NUM_PROCESSES):
+    channel, result = queue.get(timeout=2.0)
+    print "result", channel.gateway, result
diff --git a/py/doc/example/genhtml.py b/example/genhtml.py
similarity index 100%
rename from py/doc/example/genhtml.py
rename to example/genhtml.py
diff --git a/py/doc/example/genhtmlcss.py b/example/genhtmlcss.py
similarity index 100%
rename from py/doc/example/genhtmlcss.py
rename to example/genhtmlcss.py
diff --git a/py/doc/example/genxml.py b/example/genxml.py
similarity index 100%
rename from py/doc/example/genxml.py
rename to example/genxml.py
diff --git a/py/doc/example/pytest/failure_demo.py b/example/pytest/failure_demo.py
similarity index 100%
rename from py/doc/example/pytest/failure_demo.py
rename to example/pytest/failure_demo.py
diff --git a/py/doc/example/pytest/test_failures.py b/example/pytest/test_failures.py
similarity index 100%
rename from py/doc/example/pytest/test_failures.py
rename to example/pytest/test_failures.py
diff --git a/py/doc/example/pytest/test_setup_flow_example.py b/example/pytest/test_setup_flow_example.py
similarity index 100%
rename from py/doc/example/pytest/test_setup_flow_example.py
rename to example/pytest/test_setup_flow_example.py