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

3 files changed, 73 insertions, 90 deletions

diff --git a/slixmpp/stanza/iq.py b/slixmpp/stanza/iq.py
index bb46aecc..f7b222e6 100644
--- a/slixmpp/stanza/iq.py
+++ b/slixmpp/stanza/iq.py
@@ -32,6 +32,9 @@ class Iq(RootStanza):
     as a carrier stanza for an application-specific protocol instead.
 
     Example <iq> Stanzas:
+
+    .. code-block:: xml
+
         <iq to="user@example.com" type="get" id="314">
           <query xmlns="http://jabber.org/protocol/disco#items" />
         </iq>
@@ -47,20 +50,9 @@ class Iq(RootStanza):
         </iq>
 
     Stanza Interface:
-        query -- The namespace of the <query> element if one exists.
-
+        - **query**: The namespace of the <query> element if one exists.
     Attributes:
-        types -- May be one of: get, set, result, or error.
-
-    Methods:
-        __init__    -- Overrides StanzaBase.__init__.
-        unhandled   -- Send error if there are no handlers.
-        set_payload -- Overrides StanzaBase.set_payload.
-        set_query   -- Add or modify a <query> element.
-        get_query   -- Return the namespace of the <query> element.
-        del_query   -- Remove the <query> element.
-        reply       -- Overrides StanzaBase.reply
-        send        -- Overrides StanzaBase.send
+        - **types**: May be one of: get, set, result, or error.
     """
 
     namespace = 'jabber:client'
@@ -98,8 +90,9 @@ class Iq(RootStanza):
         """
         Set the XML contents of the <iq> stanza.
 
-        Arguments:
-            value -- An XML object to use as the <iq> stanza's contents
+        :param value: An XML object or a list of XML objects to use as the <iq>
+                      stanza's contents
+        :type value: list or XML object
         """
         self.clear()
         StanzaBase.set_payload(self, value)
@@ -111,8 +104,7 @@ class Iq(RootStanza):
 
         Query elements are differentiated by their namespace.
 
-        Arguments:
-            value -- The namespace of the <query> element.
+        :param str value: The namespace of the <query> element.
         """
         query = self.xml.find("{%s}query" % value)
         if query is None and value:
@@ -126,7 +118,9 @@ class Iq(RootStanza):
         return self
 
     def get_query(self):
-        """Return the namespace of the <query> element."""
+        """Return the namespace of the <query> element.
+
+        :rtype: str"""
         for child in self.xml:
             if child.tag.endswith('query'):
                 ns = child.tag.split('}')[0]
@@ -144,16 +138,15 @@ class Iq(RootStanza):
 
     def reply(self, clear=True):
         """
-        Send a reply <iq> stanza.
+        Create a new <iq> stanza replying to ``self``.
 
         Overrides StanzaBase.reply
 
         Sets the 'type' to 'result' in addition to the default
         StanzaBase.reply behavior.
 
-        Arguments:
-            clear -- Indicates if existing content should be
-                     removed before replying. Defaults to True.
+        :param bool clear: Indicates if existing content should be
+                           removed before replying. Defaults to True.
         """
         new_iq = StanzaBase.reply(self, clear=clear)
         new_iq['type'] = 'result'
@@ -168,10 +161,8 @@ class Iq(RootStanza):
 
         Overrides StanzaBase.send
 
-        Arguments:
-
-            timeout -- The length of time (in seconds) to wait for a
-                       response before an IqTimeout is raised
+        :param int timeout:  The length of time (in seconds) to wait for a
+                               response before an IqTimeout is raised
         """
 
         future = asyncio.Future()
@@ -216,20 +207,19 @@ class Iq(RootStanza):
 
         Overrides StanzaBase.send
 
-        Arguments:
-
-            callback -- Optional reference to a stream handler
-                        function. Will be executed when a reply stanza is
-                        received.
-            timeout -- The length of time (in seconds) to wait for a
-                        response before the timeout_callback is called,
-                        instead of the regular callback
-            timeout_callback -- Optional reference to a stream handler
-                        function.  Will be executed when the timeout expires
-                        before a response has been received with the
-                        originally-sent IQ stanza.
-            coroutine -- This function will return a coroutine if this argument
-                         is True.
+        :param function callback: Optional reference to a stream handler
+                                  function. Will be executed when a reply
+                                  stanza is received.
+        :param int timeout: The length of time (in seconds) to wait for a
+                            response before the timeout_callback is called,
+                            instead of the regular callback
+        :param function timeout_callback: Optional reference to a stream handler
+                                          function.  Will be executed when the
+                                          timeout expires before a response has
+                                          been received for the originally-sent
+                                          IQ stanza.
+        :param bool coroutine: This function will return a coroutine if this
+                               argument is True.
         """
         if self.stream.session_bind_event.is_set():
             matcher = MatchIDSender({
diff --git a/slixmpp/stanza/message.py b/slixmpp/stanza/message.py
index 7f9e90f5..cbb170fa 100644
--- a/slixmpp/stanza/message.py
+++ b/slixmpp/stanza/message.py
@@ -23,6 +23,9 @@ class Message(RootStanza):
     an error response.
 
     Example <message> stanzas:
+
+    .. code-block:: xml
+
         <message to="user1@example.com" from="user2@example.com">
           <body>Hi!</body>
         </message>
@@ -32,26 +35,13 @@ class Message(RootStanza):
         </message>
 
     Stanza Interface:
-        body    -- The main contents of the message.
-        subject -- An optional description of the message's contents.
-        mucroom -- (Read-only) The name of the MUC room that sent the message.
-        mucnick -- (Read-only) The MUC nickname of message's sender.
+        - **body**: The main contents of the message.
+        - **subject**: An optional description of the message's contents.
+        - **mucroom**: (Read-only) The name of the MUC room that sent the message.
+        - **mucnick**: (Read-only) The MUC nickname of message's sender.
 
     Attributes:
-        types -- May be one of: normal, chat, headline, groupchat, or error.
-
-    Methods:
-        setup       -- Overrides StanzaBase.setup.
-        chat        -- Set the message type to 'chat'.
-        normal      -- Set the message type to 'normal'.
-        reply       -- Overrides StanzaBase.reply
-        get_type    -- Overrides StanzaBase interface
-        get_mucroom -- Return the name of the MUC room of the message.
-        set_mucroom -- Dummy method to prevent assignment.
-        del_mucroom -- Dummy method to prevent deletion.
-        get_mucnick -- Return the MUC nickname of the message's sender.
-        set_mucnick -- Dummy method to prevent assignment.
-        del_mucnick -- Dummy method to prevent deletion.
+        - **types**: May be one of: normal, chat, headline, groupchat, or error.
     """
 
     name = 'message'
@@ -81,18 +71,25 @@ class Message(RootStanza):
         Overrides default stanza interface behavior.
 
         Returns 'normal' if no type attribute is present.
+
+        :rtype: str
         """
         return self._get_attr('type', 'normal')
 
     def get_parent_thread(self):
-        """Return the message thread's parent thread."""
+        """Return the message thread's parent thread.
+
+        :rtype: str
+        """
         thread = self.xml.find('{%s}thread' % self.namespace)
         if thread is not None:
             return thread.attrib.get('parent', '')
         return ''
 
     def set_parent_thread(self, value):
-        """Add or change the message thread's parent thread."""
+        """Add or change the message thread's parent thread.
+
+        :param str value: identifier of the thread"""
         thread = self.xml.find('{%s}thread' % self.namespace)
         if value:
             if thread is None:
@@ -128,10 +125,11 @@ class Message(RootStanza):
         Sets proper 'to' attribute if the message is from a MUC, and
         adds a message body if one is given.
 
-        Arguments:
-            body  -- Optional text content for the message.
-            clear -- Indicates if existing content should be removed
-                     before replying. Defaults to True.
+        :param str body:  Optional text content for the message.
+        :param bool clear: Indicates if existing content should be removed
+                           before replying. Defaults to True.
+
+        :rtype: :class:`~.Message`
         """
         new_message = StanzaBase.reply(self, clear)
 
@@ -152,6 +150,8 @@ class Message(RootStanza):
         Return the name of the MUC room where the message originated.
 
         Read-only stanza interface.
+
+        :rtype: str
         """
         if self['type'] == 'groupchat':
             return self['from'].bare
@@ -163,6 +163,8 @@ class Message(RootStanza):
         Return the nickname of the MUC user that sent the message.
 
         Read-only stanza interface.
+
+        :rtype: str
         """
         if self['type'] == 'groupchat':
             return self['from'].resource
diff --git a/slixmpp/stanza/presence.py b/slixmpp/stanza/presence.py
index e1b8c0bc..1e8a940e 100644
--- a/slixmpp/stanza/presence.py
+++ b/slixmpp/stanza/presence.py
@@ -27,6 +27,9 @@ class Presence(RootStanza):
     to help keep the network running smoothly.
 
     Example <presence> stanzas:
+
+    .. code-block:: xml
+
         <presence />
 
         <presence from="user@example.com">
@@ -40,24 +43,14 @@ class Presence(RootStanza):
         <presence to="user@otherhost.com" type="subscribe" />
 
     Stanza Interface:
-        priority -- A value used by servers to determine message routing.
-        show     -- The type of status, such as away or available for chat.
-        status   -- Custom, human readable status message.
+        - **priority**: A value used by servers to determine message routing.
+        - **show**: The type of status, such as away or available for chat.
+        - **status**: Custom, human readable status message.
 
     Attributes:
-        types     -- One of: available, unavailable, error, probe,
-                         subscribe, subscribed, unsubscribe,
-                         and unsubscribed.
-        showtypes -- One of: away, chat, dnd, and xa.
-
-    Methods:
-        setup        -- Overrides StanzaBase.setup
-        reply        -- Overrides StanzaBase.reply
-        set_show     -- Set the value of the <show> element.
-        get_type     -- Get the value of the type attribute or <show> element.
-        set_type     -- Set the value of the type attribute or <show> element.
-        get_priority -- Get the value of the <priority> element.
-        set_priority -- Set the value of the <priority> element.
+        - **types**: One of: available, unavailable, error, probe,
+          subscribe, subscribed, unsubscribe, and unsubscribed.
+        - **showtypes**: One of: away, chat, dnd, and xa.
     """
 
     name = 'presence'
@@ -93,8 +86,7 @@ class Presence(RootStanza):
         """
         Set the value of the <show> element.
 
-        Arguments:
-            show -- Must be one of: away, chat, dnd, or xa.
+        :param str show: Must be one of: away, chat, dnd, or xa.
         """
         if show is None:
             self._del_sub('show')
@@ -119,8 +111,7 @@ class Presence(RootStanza):
         Set the type attribute's value, and the <show> element
         if applicable.
 
-        Arguments:
-            value -- Must be in either self.types or self.showtypes.
+        :param str value: Must be in either self.types or self.showtypes.
         """
         if value in self.types:
             self['show'] = None
@@ -146,14 +137,15 @@ class Presence(RootStanza):
         Bot clients should typically use a priority of 0 if the same
         JID is used elsewhere by a human-interacting client.
 
-        Arguments:
-            value -- An integer value greater than or equal to 0.
+        :param int value: An integer value greater than or equal to 0.
         """
         self._set_sub_text('priority', text=str(value))
 
     def get_priority(self):
         """
         Return the value of the <presence> element as an integer.
+
+        :rtype: int
         """
         p = self._get_sub_text('priority')
         if not p:
@@ -166,13 +158,12 @@ class Presence(RootStanza):
 
     def reply(self, clear=True):
         """
-        Set the appropriate presence reply type.
+        Create a new reply <presence/> stanza from ``self``.
 
         Overrides StanzaBase.reply.
 
-        Arguments:
-            clear -- Indicates if the stanza contents should be removed
-                     before replying. Defaults to True.
+        :param bool clear: Indicates if the stanza contents should be removed
+                           before replying. Defaults to True.
         """
         new_presence = StanzaBase.reply(self, clear)
         if self['type'] == 'unsubscribe':