From b98555c512ddb7452c9a217b1024b9e3163dea99 Mon Sep 17 00:00:00 2001
From: Lance Stout <lancestout@gmail.com>
Date: Thu, 18 Aug 2011 16:32:06 -0700
Subject: [PATCH] Update the README

Now includes how to generate the docs, run tests, and the basic
boilerplate for Sleek based projects.
---
 README.rst | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/README.rst b/README.rst
index dc29b639..a8b69ac9 100644
--- a/README.rst
+++ b/README.rst
@@ -66,6 +66,84 @@ help with SleekXMPP.
 **Chat**
     `sleek@conference.jabber.org <xmpp:sleek@conference.jabber.org?join>`_
 
+Documentation and Testing
+-------------------------
+
+Documentation can be found both inline in the code, and as a Sphinx project in ``/docs``.
+To generate the Sphinx documentation, follow the commands below. The HTML output will
+be in ``docs/_build/html``::
+
+    cd docs
+    make html
+    open _build/html/index.html
+
+To run the test suite for SleekXMPP::
+
+    python testall.py
+
+
+The SleekXMPP Boilerplate
+-------------------------
+
+Projects using SleekXMPP tend to follow a basic pattern for setting up client/component
+connections and configuration. Here is the gist of the boilerplate needed for a SleekXMPP
+based project. See the documetation or examples directory for more detailed archetypes for
+SleekXMPP projects::
+
+    import logging
+
+    from sleekxmpp import ClientXMPP
+    from sleekxmpp.exceptions import IqError, IqTimeout
+
+
+    class EchoBot(ClientXMPP):
+
+        def __init__(self, jid, password):
+            ClientXMPP.__init__(self, jid, password)
+
+            self.add_event_handler("session_start", self.start)
+            self.add_event_handler("message", self.message)
+
+        def start(self, event):
+            self.send_presence()
+
+            # Most get_* methods from plugins use Iq stanzas, which
+            # can generate IqError and IqTimeout exceptions
+            try:
+                self.get_roster()
+            except IqError as err:
+                logging.error('There was an error getting the roster')
+                logging.error(err.iq['error']['condition'])
+                self.disconnect()
+            except IqTimeout:
+                logging.error('Server is taking too long to respond')
+                self.disconnect()
+
+        def message(self, msg):
+            if msg['type'] in ('chat', 'normal'):
+                msg.reply("Thanks for sending\n%(body)s" % msg).send()
+
+
+    if __name__ == '__main__':
+        # Ideally use optparse or argparse to get JID, 
+        # password, and log level.
+
+        logging.basicConfig(level=logging.DEBUG,
+                            format='%(levelname)-8s %(message)s')
+
+        xmpp = EchoBot('somejid@example.com', 'use_getpass')
+        xmpp.register_plugin('xep_0030') # Service Discovery
+        xmpp.register_plugin('xep_0199') # XMPP Ping
+
+        # If you are working with an OpenFire server, you will need
+        # to useuterborg Larsson version:
+        # xmppissl_version = ssl.PROTOCOL_SSLv3
+
+        if xmpp.connect():
+            xmpp.process(block=True)
+        else:
+            print("Unable to connect.")
+
 
 Credits
 -------