Update the documentation and examples

- update most of the examples with slixmpp
- change the help channels pointed out in the doc
- add a page listing differences from slixmpp and how to use asyncio
  nicely with slixmpp
- fix some in-code rst documentation

10 files changed, 43 insertions, 30 deletions

diff --git a/docs/api/stanza/iq.rst b/docs/api/stanza/iq.rst
new file mode 100644
index 00000000..0a7d7ffb
--- /dev/null
+++ b/docs/api/stanza/iq.rst
@@ -0,0 +1,8 @@
+IQ Stanza
+=========
+
+.. module:: slixmpp.stanza
+
+.. autoclass:: Iq
+    :members:
+
diff --git a/docs/api/stanza/message.rst b/docs/api/stanza/message.rst
new file mode 100644
index 00000000..f01c62a7
--- /dev/null
+++ b/docs/api/stanza/message.rst
@@ -0,0 +1,7 @@
+Message Stanza
+==============
+
+.. module:: slixmpp.stanza
+
+.. autoclass:: Message
+    :members:
diff --git a/docs/api/stanza/presence.rst b/docs/api/stanza/presence.rst
new file mode 100644
index 00000000..15ac7bf9
--- /dev/null
+++ b/docs/api/stanza/presence.rst
@@ -0,0 +1,8 @@
+Presence Stanza
+===============
+
+.. module:: slixmpp.stanza
+
+.. autoclass:: Presence
+    :members:
+
diff --git a/docs/api/stanza/rootstanza.rst b/docs/api/stanza/rootstanza.rst
new file mode 100644
index 00000000..83d9f49b
--- /dev/null
+++ b/docs/api/stanza/rootstanza.rst
@@ -0,0 +1,8 @@
+Root Stanza
+===========
+
+.. module:: slixmpp.stanza.rootstanza
+
+.. autoclass:: RootStanza
+    :members:
+
diff --git a/docs/api/xmlstream/filesocket.rst b/docs/api/xmlstream/filesocket.rst
deleted file mode 100644
index eff062d8..00000000
--- a/docs/api/xmlstream/filesocket.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. module:: slixmpp.xmlstream.filesocket
-
-.. _filesocket:
-
-Python 2.6 File Socket Shims
-============================
-
-.. autoclass:: FileSocket
-    :members:
-
-.. autoclass:: Socket26
-    :members:
diff --git a/docs/api/xmlstream/handler.rst b/docs/api/xmlstream/handler.rst
index ab8091a3..9d2f5aba 100644
--- a/docs/api/xmlstream/handler.rst
+++ b/docs/api/xmlstream/handler.rst
@@ -10,15 +10,19 @@ The Basic Handler
 
 Callback
 --------
-.. module:: slixmpp.xmlstream.handler.callback
+.. module:: slixmpp.xmlstream.handler
 
 .. autoclass:: Callback
     :members:
 
+CoroutineCallback
+-----------------
+
+.. autoclass:: CoroutineCallback
+    :members:
 
 Waiter
 ------
-.. module:: slixmpp.xmlstream.handler.waiter
 
 .. autoclass:: Waiter
     :members:
diff --git a/docs/api/xmlstream/jid.rst b/docs/api/xmlstream/jid.rst
index 1844b75a..2f0c65d0 100644
--- a/docs/api/xmlstream/jid.rst
+++ b/docs/api/xmlstream/jid.rst
@@ -1,7 +1,7 @@
 Jabber IDs (JID)
 =================
 
-.. module:: slixmpp.xmlstream.jid
+.. module:: slixmpp.jid
 
 .. autoclass:: JID
     :members:
diff --git a/docs/api/xmlstream/scheduler.rst b/docs/api/xmlstream/scheduler.rst
deleted file mode 100644
index 59752eca..00000000
--- a/docs/api/xmlstream/scheduler.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-=========
-Scheduler
-=========
-
-.. module:: slixmpp.xmlstream.scheduler
-
-.. autoclass:: Task
-    :members:
-
-.. autoclass:: Scheduler
-    :members:
diff --git a/docs/api/xmlstream/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst
index 216ceebe..ad43a44a 100644
--- a/docs/api/xmlstream/stanzabase.rst
+++ b/docs/api/xmlstream/stanzabase.rst
@@ -61,8 +61,8 @@ interacting with a given :term:`stanza` a :term:`stanza object`.
 To make dealing with more complicated and nested :term:`stanzas <stanza>`
 or XML chunks easier, :term:`stanza objects <stanza object>` can be
 composed in two ways: as iterable child objects or as plugins. Iterable
-child stanzas, or :term:`substanzas`, are accessible through a special
-``'substanzas'`` interface. This option is useful for stanzas which
+child stanzas, or :term:`substanzas <substanza>`, are accessible through a
+special ``'substanzas'`` interface. This option is useful for stanzas which
 may contain more than one of the same kind of element. When there is
 only one child element, the plugin method is more useful. For plugins,
 a parent stanza object delegates one of its XML child elements to the
diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst
index 8d75f1db..68abbdb6 100644
--- a/docs/api/xmlstream/tostring.rst
+++ b/docs/api/xmlstream/tostring.rst
@@ -28,7 +28,7 @@ namespace because that is already declared by the stream header. But, if
 you create a :class:`~slixmpp.stanza.message.Message` instance and dump
 it to the terminal, the ``jabber:client`` namespace will appear.
 
-.. autofunction:: tostring
+.. autofunction:: slixmpp.xmlstream.tostring
 
 Escaping Special Characters
 ---------------------------
@@ -43,4 +43,5 @@ In the future, the use of CDATA sections may be allowed to reduce the
 size of escaped text or for when other XMPP processing agents do not
 undertand these entities.
 
-.. autofunction:: xml_escape
+..
+    autofunction:: xml_escape