Add developer documentation for bots

docs/bots-guide.md

@@ -0,0 +1,192 @@
+# Developing bots
+**This feature is still experimental**
+The contrib_bots system is a new part of Zulip that allows bot developers to write a large class of bots by simply reacting to message.
+
+With bots, you *can*
+
+* intercept and view messages sent by users on Zulip
+* send out new messages
+
+With bots, you *cannot*
+
+* modify an intercepted message (you have to send a new message)
+* send messages in the name of other users
+* intercept private messages
+
+
+On this page you'll find:
+
+* A step-by-step [tutorial](#how-to-deploy-a-bot) on how to deploy a bot.
+* A step-by-step [tutorial](#how-to-develop-a-bot) on how to develop a bot.
+* A [documentation](#bot-api) of the bot API.
+* Common [problems](#common-problems) when developing/deploying bots and their solutions.
+
+Contributions to this guide are very welcome, so if you run into any
+issues following these instructions or come up with any tips or tools
+that help writing bots, please visit chat.zulip.org, open an issue, or submit a pull request
+to share your ideas!
+
+## How to deploy a bot
+This guide will show you how to deploy a bot on your running Zulip server. It presumes that you already have a fully implemented `<my-bot>.py` bot and now want to try it out.
+
+1. Copy your bot `<my-bot>.py` to `~/zulip/contrib_bots/lib/`.
+ * This is the place where all Zulip bots are stored.
+ * You can also test out already existing bots in this directory.
+2. Run your Zulip server. Bots can only be deployed on running systems.
+3. Register a new bot at your Zulip server's web interface.
+ * Navigate to *Settings* -> *Your Bots* -> *Add a New Bot*, fill out the form and click on *Create Bot*.
+ * A new bot should appear in the *Your Bots* panel.
+4. Add the bot's configuration file on your Zulip server.
+ * In the *Your Bots* panel, click on the green icon to download its configuration file *.zuliprc* (the structure of this file is explained [here](#configuration-file)
+ * Copy the file to a destination of your choice on your Zulip server, e.g. to `~/.zuliprc`or ~/zuliprc-test.
+5. Subscribe the bot to any streams that the bot needs to read message from or write message to.55
+ * To subscribe your bot to streams, navigate to *Manage Streams*. Select a stream and add your bot by its email address (the address you assigned in step 2).
+ * Now, the bot will do its job on the streams you subscribed it to.
+6. Run the bot.
+ * On your Zulip server, navigate to `~/zulip/contrib_bots/`
+ * Run `python run.py ~/zulip/contrib_bots/<my-bot>.py --config-file ~/.zuliprc
+ * Check the output of the command. It should start with the text the `usage` function returns, followed by logging output similar to this:
+
+>INFO:root:starting message handling...
+>INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost
+
+* Congrats! Now, your bot should be ready to test on the streams you subscribed it to.
+
+### Test the `followup.py` bot
+1. Do the previous steps for the `followup.py` bot.
+2. Subscribe the bot to *followup* and another stream, e.g. *social*.
+3. Send a message to the stream *social* . If everything works, a copy of this message should now pop up in the *followup* stream.
+
+## How to develop a bot
+
+Below explains the structure of a bot `<my-bot>.py`. You can use this as boilerplate code for developing your own bot.
+
+Every bot is built upon this structure:
+```
+class FollowupHandler(object):
+    '''
+    A docstring documenting this bot.
+    '''
+
+    def usage(self):
+        return '''Your description of the bot'''
+
+    def triage_message(self, message):
+        #add your code here
+
+    def handle_message(self, message, client, state_handler):
+# add your code here
+
+handler_class = FollowupHandler
+```
+* The class name (in this case *FollowupHandler*) can be defined by you and should match the name of your bot. To register your bot's class, adjust the last line `handler_class = FollwupHandler` to match your class name.
+* Every bot needs to implement the functions
+ * `usage(self)`
+ * `triage_message(self, message)`
+ * `handle_message(self, message, client)`
+* These functions are documented in the [next section](#bot-API).
+
+## Bot API
+This sections documents the functions every bot needs to implement and the structure of the bot's config file.
+
+### usage(self)
+Is called by the system to obtain information about this bot.
+#### Arguments
+* self - the instance the method is called on.
+#### Return values
+* A string describing the bot's functionality
+#### Example implementation
+```
+def usage(self):
+    return '''
+        This plugin will allow users to flag messages
+        as being follow-up items.  Users should preface
+        messages with "@followup".
+        Before running this, make sure to create a stream
+        called "followup" that your API user can send to.
+        '''
+```
+
+### triage_message(self, message)
+Is called by the system when a message was sent.
+#### Arguments
+* self - the instance the method is called on.
+* message - an object containing information about the message, e.g.
+ * content - the content of the message
+ * content_type - the type of the content, e.g. *'text/x-markdown'* for normal messages
+ * display_recipient - the name of the stream the message is sent to (string)
+ * is_mentioned - is the bot pinged with an '@' in the message? (boolean)
+ * sender_email - email of the sender (string)
+ * sender_full_name - full name of the sender (string)
+ * subject - topic of the message (string)
+ * timestamp - when was the message sent (integer)
+
+ ####Return values
+ * True if the bot should react to this message
+ * False otherwise
+
+ ####Example implementation
+```
+def triage_message(self, message):
+original_content = message['content']
+    if message['display_recipient'] == 'followup':
+        return False
+    is_follow_up = (original_content.startswith('@followup') or
+                        original_content.startswith('@follow-up'))
+    return is_follow_up
+```
+
+### handle_message(self, message, client)
+Is called when `triage_message` returns true, handles user message.
+#### Arguments
+* self - the instance the method is called on.
+* message - an object containing information about the message, e.g.
+ * content - the content of the message
+ * content_type - the type of the content, e.g. *'text/x-markdown'* for normal messages
+ * display_recipient - the name of the stream the message is sent to (string)
+ * is_mentioned - is the bot pinged with an '@' in the message? (boolean)
+ * sender_email - email of the sender (string)
+ * sender_full_name - full name of the sender (string)
+ * subject - topic of the message (string)
+ * timestamp - when was the message sent (integer)
+* client - used to interact with the server, e.g. to send a message
+ * use client.send_message(message) to send a message
+* state_handler - used to save states/information of the bot**beta**
+ * use `state_handler.set_state(state)` to set a state (any object)
+ * use `state_handler.get_state()` to retrieve the state set. Returns a `NoneType` object if no state is set.
+
+ ####Return values
+ None.
+
+ ####Example implementation
+ ```
+ def handle_message(self, message, client, state_handler):
+    original_content = message['content']
+    original_sender = message['sender_email']
+    new_content = original_content.replace('@followup',
+                                           'from %s:' % (original_sender,))
+
+    client.send_message(dict(
+        type='stream',
+        to='followup',
+        subject=message['sender_email'],
+        content=new_content,
+    ))
+ ```
+
+ ###Configuration file
+ ```
+ [api]
+key=<api-key>
+email=<email>
+site=<dev-url>
+ ```
+* key - the API key you created for the bot. This is how Zulip knows the request is from an authorized user.
+* email - the email address of the bot, e.g. `some-bot@zulip.com`
+* site - your development environment URL. If you are working on a development environment hosted on your computer, use `localhost:9991`
+## Common problems
+* I modified my bot's code, yet the changes don't seem to have an effect.
+ * Assure that you restarted the `run.py` script.
+ * Assure that your API config file is correct (download the config file from the server)
+* My bot works only on some streams.
+ * Subscribe your bot to other streams, as described [here](#how-to-deploy-a-bot).

docs/index.rst

@@ -76,6 +76,7 @@ Contents:
    :caption: Developer tutorials
 
    integration-guide
+   bots-guide
    new-feature-tutorial
    writing-views
    life-of-a-request