Document the IRC bot

Summary: Write a little documentation about how to get the IRC bot running since
there's a reasonable process with some examples but no documentation.

Test Plan: Generated, read the documentation.

Reviewers: btrahan, jungejason

Reviewed By: jungejason

CC: iAladdin, aran, jungejason

Maniphest Tasks: T686

Differential Revision: 1244

src/docs/technical/ircbot.diviner

@@ -0,0 +1,81 @@
+@title IRCBot Technical Documentation
+@group irc
+
+Configuring and extending the IRCBot.
+
+= Overview =
+
+Phabricator includes a simple IRC bot daemon, which is primarily intended as
+an example of how you can write an external script that interfaces with
+Phabricator over Conduit and does some kind of useful work. If you use IRC, you
+can also have the bot hang out in your channel.
+
+NOTE: The IRC bot is somewhat experimental and not very mature.
+
+= Configuring the Bot =
+
+The bot reads a JSON configuration file. You can find an example in:
+
+  resources/ircbot/example_config.json
+
+These are the configuration values it reads:
+
+  - ##server## String, required, the server to connect to.
+  - ##port## Int, optional, the port to connect to (defaults to 6667).
+  - ##ssl## Bool, optional, whether to connect via SSL or not (defaults to
+    false).
+  - ##nick## String, nickname to use.
+  - ##user## String, optional, username to use (defaults to ##nick##).
+  - ##pass## String, optional, password for server.
+  - ##nickpass## String, optional, password for NickServ.
+  - ##join## Array, list of channels to join.
+  - ##handlers## Array, list of handlers to run. These are like plugins for the
+    IRCBot.
+  - ##conduit.uri##, ##conduit.user##, ##conduit.cert## Conduit configuration,
+    see below.
+
+= Handlers =
+
+You specify a list of "handlers", which are basically plugins or modules for
+the IRC bot. These are the default handlers available:
+
+  - @{class:PhabricatorIRCProtocolHandler} This handler implements the raw IRC
+    protocol (e.g., responding with PONG when the server sends PING). You should
+    probably leave it in the handler list unless you implement the protocol
+    details yourself in another handler.
+  - @{class:PhabricatorIRCObjectNameHandler} This handler looks for users
+    mentioning Phabricator objects like "T123" and "D345" in chat, looks them
+    up, and says their name with a link to the object. Requires conduit.
+
+You can also write your own handlers, by extending
+@{class:PhabricatorIRCHandler}.
+
+= Conduit =
+
+Some handlers (e.g., @{class:PhabricatorIRCObjectNameHandler}) need to read data
+from Phabricator. They do this over Conduit, Phabricator's HTTP API. You can
+use this method to allow other scripts or programs to access Phabricator's data
+from different servers and in different languages.
+
+To allow the bot to access Conduit, you need to create a user that it can login
+with. To do this, login to Phabricator as an administrator and go to
+##People -> Create New Account##. Create a new account and flag them as a
+"System Agent". Then in your configuration file, set these parameters:
+
+  - ##conduit.uri## The URI for your Phabricator install, like
+    ##http://phabricator.example.com/##
+  - ##conduit.user## The username your bot should login to Phabricator with --
+    whatever you selected above, like ##phabot##.
+  - ##conduit.cert## The user's certificate, from the "Conduit Certificate" tab
+    in the user's administrative view.
+
+Now the bot should be able to connect to Phabricator via Conduit.
+
+= Starting the Bot =
+
+The bot is a Phabricator daemon, so start it with ##phd##:
+
+  ./bin/phd launch ircbot <absolute_path_to_config_file>
+
+If you have issues you can try ##debug## instead of ##launch##, see
+@{article:Managing Daemons with phd} for more information.