Write config docs. Friendly-up hamper.conf.dist.

docs/config.mkd

@@ -0,0 +1,81 @@
+# Configuration
+
+## Core configuration
+
+Configuration for hamper is stored in `hamper.conf`, which is parsed as
+[YAML][]. It can also be read from environment variables, as detailed below.
+
+[YAML]: http://www.yaml.com
+
+The core of hamper only uses a few configuration options.
+
+* `nickname` - The nick to use when connecting to IRC. (Required)
+* `server` - The hostname of the server to connect to. Try something like
+  `irc.freenode.net`. (Required)
+* `port` - The port to connect to the server on. Try `6667`. Make sure to use 
+  an SSL enabled port if `ssl` is enabled. (Required)
+* `db` - This is a database URL as described [here][dburl]. This is not
+  required. If you leave it unspecified, Hamper will use a in-memory
+  database instead. The url `sqlite:///hamper.db` will make a sqlite
+  database in a file named `hamper.db` in the current directory.
+* `channels` - A list of channels to join, including the leading `#`.
+* `plugins` - A list of plugins to load.
+* `ssl` - If true, Hamper will use SSL to connect to the server.
+* `password` - Iff this is supplied, Hamper will attempt to authenticate with
+  NickServ using `nickname` and this password. If this happens, it will delay
+  loading channels until after NickServ has responded.
+
+## Plugin Configuration
+
+Some plugins require extra configuration. These settings go in the same config
+file as the core settings above. For each of these plugins, the settings go
+under a key of the plugin's name. For example, the configuration for `tinyurl`
+might look like this in `hamper.conf`:
+
+```yaml
+tinyurl:
+    excluded-urls:
+        - imgur.com
+        - gist.github.com
+```
+
+> External plugins may require other configuration not listed here.
+
+### [Tinyurl][]
+
+This plugin will automatically shorten long urls pasted into the channel.
+
+* `min-length` - The length of the shortest url that the plugin will attempt to
+  shorten. (Default: 40)
+* `excluded-urls` - A list of urls to ignore. If any of these a substring of
+  the seen urls, they won't be shortened. (Default:
+  `['imgur.com', 'gist.github.com', 'pastebin.com']`).
+
+[Tinyurl]: plugins/tinyurl.mkd
+
+### [Timez][]
+
+The timez plugin allows you to look up local time for different timezones.
+
+* `api-key` - An API key for the service. Get it from [here][timezapi]. The 
+  free api should work fine.
+
+[Timez]: plugins/timez.mkd
+[timezapi]: http://developer.worldweatheronline.com 
+
+
+## Environment Variables
+
+Hamper can also pull in settings from environment variables, which is useful
+for environments like [Heroku][] or [Docker][]. Environment variables are
+mapped directly to top level configuration variables. For example, to change
+the IRC port to 8001, you could set the environment variables `port=8001`.
+
+If an environment variable is valid YAML, it will be parsed as such. For
+example, you could configure Timez's api-key like
+`timez={"api-key": "LOLAPIKEY"}`.
+
+If you aren't sure if you need to do this, you likely don't have to. It's
+pretty specialized. Be aware of any escaping you may have to do to set these
+environment variables.
+

docs/quickstart.mkd

@@ -1,6 +1,6 @@
-# Hamper
+# Quickstart
 
-## Getting Started
+## Installation
 
 You'll need Python 2.7, and the tools [Virtualenv][venv] and [Pip][pip] are
 highly recommended.
@@ -18,6 +18,12 @@ $ virtualenv venv
 $ source venv/bin/activate
 ```
 
+> Note that on systems like Arch Linux, where Python 3 is the default, you will
+> have to specificy that you want to use Python 2. In particular, you should
+> use the command `virtualenv2` instead of `virtualenv`. This will create a
+> Python 2 virtualenv, so you would have to worry about it for the rest of this
+> guide.
+
 To install the requirements, run
 
 ```bash
@@ -49,14 +55,14 @@ template, `hamper.conf.dist`. Copy that file, name the copy
 In particular, you problably want to change the `nickname`, `server`,
 `port`, `channels`, and `plugins`. These should be pretty straight
 forward, but if you want more details, read
-[the configuration docs][docs].
+[the configuration docs][config].
 
-[docs]: docs.mkd
+[config]: config.mkd
 
 ## Running
 
-The main entry point for Hamper is `scripts/hamper`, which imports the
-bot, does any needed path mangling, and calls the main function.
+The main entry point for Hamper is `scripts/hamper`, which imports the bot,
+tries to set up the Python path if needed, and runs the main function.
 
 ```bash
 $ scripts/hamper

hamper.conf.dist

@@ -1,34 +1,14 @@
+# Sample configuration file for Hamper
 nickname: cool_bot
-
-# Uncomment and set password for nickserv auth
-# password:
-
 server: irc.freenode.net
 port: 6667
+
 db: "sqlite:///hamper.db"
 
-# Uncomment and setup .acl file if you need it
-# acl: hamper.acl
+channels:
+    - "#hamper-testing"
 
-channels: ["#awesome-channel", "#cool-channel"]
 plugins:
-    - quit
     - sed
-    - lmgtfy
     - friendly
     - ponies
-    - botsnack
-    - karma
-    - plugins
-
-# Sign up for an API key here http://developer.worldweatheronline.com
-# This plugin allows you to look up local time for different timezones
-# timez:
-#    api-key:
-
-tinyurl:
-    # Sites that should not have their links shortened
-    excluded-urls:
-        - imgur.com
-        - gist.github.com
-        - pastebin.com