From c1b51b2bda8c6b8a4b726ca482cf705b4507eda9 Mon Sep 17 00:00:00 2001
From: Tobias Oberstein <tobias.oberstein@tavendo.de>
Date: Wed, 30 Jul 2014 20:31:04 +0200
Subject: [PATCH] work on docs

---
 doc/websocket/examples.rst                    | 90 ++++++++++++++++---
 .../asyncio/websocket/slowsquare/README.md    |  1 +
 examples/asyncio/websocket/testee/README.md   |  3 +
 3 files changed, 83 insertions(+), 11 deletions(-)
 create mode 100644 examples/asyncio/websocket/testee/README.md

diff --git a/doc/websocket/examples.rst b/doc/websocket/examples.rst
index e8a00c6c..b8a262e6 100644
--- a/doc/websocket/examples.rst
+++ b/doc/websocket/examples.rst
@@ -4,29 +4,97 @@ WebSocket Examples
 ==================
 
 Basic Examples
-++++++++++++++
+--------------
 
-* WebSocket Echo:  `Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo>`__  - `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/websocket/echo>`__
-* Slow Square: `Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/slowsquare>`__  - `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/websocket/slowsquare>`__
-* Testee: `Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/testee>`__  - `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/websocket/testee>`__
+.. note::
+   The examples here demonstrate WebSocket programming with |ab| and are available in Twisted and asyncio-based variants respectively.
+
+Echo
+....
+
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo>`__  / `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/websocket/echo>`__
+
+A simple WebSocket echo server and client.
+
+Slow Square
+............
+
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/slowsquare>`__  / `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/websocket/slowsquare>`__
+
+This example shows a WebSocket server that will receive a JSON encode float over WebSocket, slowly compute the square, and send back the result.
+The example is intended to demonstrate how to use co-routines inside WebSocket handlers.
 
 
-Additional Examples (Twisted only)
-++++++++++++++++++++++++++++++++++
+Testee
+......
 
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/testee>`__  / `asyncio <https://github.com/tavendo/AutobahnPython/blob/master/examples/asyncio/websocket/testee>`__
+
+The example implements a *testee* for testing against `Autobahn|Testsuite <http://autobahn.ws/testsuite>`_.
+
+-----------
+
+
+Additional Examples
+-------------------
+
+.. note::
+   The examples here demonstrate various further features and aspects of WebSocket programming with |ab|. However, these examples are **currently only available for Twisted**.
+
+
+Secure WebSocket
+................
+
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_tls>`__
+
+How to run WebSocket over TLS ("wss").
+
+
+WebSocket and Twisted Web
+.........................
+
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_site>`__
+
+How to run WebSocket under Twisted Web. This is a very powerful feature, as it allows you to create a complete HTTP(S) resource hierarchy with different services like static file serving, REST and WebSocket combined under one server.
+
+
+Twisted Web, WebSocket and WSGI
+...............................
+
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_wsgi>`__
+
+This example shows how to run Flask (or any other WSGI compliant Web thing) under Twisted Web and combine that with WebSocket.
+
+
+Secure WebSocket and Twisted Web
+................................
+
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_site_tls>`__
+
+A variant of the previous example that runs a HTTPS server with secure WebSocket on a subpath.
+
+
+WebSocket Ping-Pong
+...................
+
+`Twisted <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/ping>`__
+
+The example demonstrates how to trigger and process WebSocket pings and pongs.
+
+
+More
+....
+
+* `WebSocket Authentication with Mozilla Persona <https://github.com/tavendo/AutobahnPython/tree/master/examples/twisted/websocket/auth_persona>`_
 * `Broadcasting over WebSocket <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/broadcast>`_
 * `WebSocket Compression <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_compressed>`_
 * `WebSocket over Twisted Endpoints <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_endpoints>`_
 * `Using HTTP Headers with WebSocket <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_httpheaders>`_
 * `WebSocket on Multicore <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_multicore>`_
 * `WebSocket as a Twisted Service <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_service>`_
-* `Running WebSocket under Twisted Web <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_site>`_
-* `Running secure WebSocket under Twisted Web <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_site_tls>`_
-* `WebSocket Echo over secure WebSocket <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_tls>`_
 * `WebSocket Echo Variants <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_variants>`_
 * `WebSocket Fallbacks <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_wsfallbacks>`_
-* `WebSocket and WSGI/Flask <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/echo_wsgi>`_
 * `Using multiple WebSocket Protocols <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/multiproto>`_
-* `WebSocket Pings/Pongs <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/ping>`_
 * `Streaming WebSocket <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/streaming>`_
 * `Wrapping Twisted Protocol/Factories over WebSocket <https://github.com/tavendo/AutobahnPython/blob/master/examples/twisted/websocket/wrapping>`_
+* `Using wxPython with Autobahn <https://github.com/tavendo/AutobahnPython/tree/master/examples/twisted/websocket/wxpython>`_
diff --git a/examples/asyncio/websocket/slowsquare/README.md b/examples/asyncio/websocket/slowsquare/README.md
index adfb2464..b11f8cde 100644
--- a/examples/asyncio/websocket/slowsquare/README.md
+++ b/examples/asyncio/websocket/slowsquare/README.md
@@ -6,6 +6,7 @@ This example is intended to demonstrate how to use coroutines inside WebSocket h
 
 > This example uses the Asyncio integration of **Autobahn**|Python. You can find the corresponding example using the Twisted integration [here](https://github.com/tavendo/AutobahnPython/tree/master/examples/twisted/websocket/slowsquare).
 > 
+
 ## Running
 
 Run the server (Python 3)
diff --git a/examples/asyncio/websocket/testee/README.md b/examples/asyncio/websocket/testee/README.md
new file mode 100644
index 00000000..d6d32242
--- /dev/null
+++ b/examples/asyncio/websocket/testee/README.md
@@ -0,0 +1,3 @@
+# Autobahn Testsuite Testee
+
+This is an asyncio-based testee for testing against [Autobahn|Testsuite](http://autobahn.ws/testsuite).
\ No newline at end of file