docs: improve docs for contrib_bots.
-# Overview
+# Contrib Bots:
This is the documentation for an experimental new system for writing
bots that react to messages.
@@ -9,13 +9,12 @@ bots that react to messages sent by users.
This document explains how to run the code, and it also
talks about the architecture for creating bots.
-## Design goals
+## Design Goals
The goal is to have a common framework for hosting a bot that reacts
to messages in any of the following settings:
-* Run as a long-running process using `call_on_each_event`
- (implemented today).
+* Run as a long-running process using `call_on_each_event`.
* Run via a simple web service that can be deployed to PAAS providers
and handles outgoing webhook requests from Zulip.
@@ -24,7 +23,11 @@ to messages in any of the following settings:
which would be done for high quality, reusable bots; we would have a
nice "bot store" sort of UI for browsing and activating them.
-## Running bots
+* Run locally by our technically inclined users for bots that require
+ account specific authentication, for example: a gmail bot that lets
+ one send emails directly through Zulip.
+
+## Running Bots
Here is an example of running the "follow-up" bot from
inside a Zulip repo (and in your remote instance):
@@ -53,6 +56,8 @@ page to create a user-owned bot.
key=<your api key>
site=https://zulip.somewhere.com
+When you run your bot, make sure to point it to the correct location
+of your `.zuliprc`.
### Third Party Configuration
@@ -66,7 +71,10 @@ information anywhere in your Zulip directory. Instead,
create a separate configuration file for the third party's
configuration in your home directory.
-### Python dependencies
+Any bots that require this will have instructions on
+exactly how to create or access this information.
+
+### Python Dependencies
If your module requires Python modules that are not either
part of the standard Python library or the Zulip API
@@ -100,8 +108,8 @@ Each bot library simply needs to do the following:
`triage_message`, and `handle_message`.
- Set `handler_class` to be the name of that class.
-(We make this a two-step process, so that you can give
-a descriptive name to your handler class.)
+(We make this a two-step process to reduce code repetition
+and to add abstraction.)
## Portability
@@ -128,6 +136,7 @@ in a server-side environment.
## Other approaches
If you are not interested in running your bots on the
-server, then you can still use the full Zulip API. The
-hope, though, is that this architecture will make
-writing simple bots a quick/easy process.
+server, then you can still use the full Zulip API and run
+them locally. The hope, though, is that this
+architecture will make writing simple bots a quick/easy
+process.
