From bf093ceebf29d8518f7e0687c435185f59feb879 Mon Sep 17 00:00:00 2001 From: Mike Cooper Date: Sat, 15 Feb 2014 17:21:25 -0800 Subject: [PATCH] Write config docs. Friendly-up hamper.conf.dist. --- docs/config.mkd | 81 +++++++++++++++++++++++++++++++++++++++++++++ docs/quickstart.mkd | 18 ++++++---- hamper.conf.dist | 28 +++------------- 3 files changed, 97 insertions(+), 30 deletions(-) create mode 100644 docs/config.mkd diff --git a/docs/config.mkd b/docs/config.mkd new file mode 100644 index 0000000..be9bb76 --- /dev/null +++ b/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. + diff --git a/docs/quickstart.mkd b/docs/quickstart.mkd index bb1280a..013b4d3 100644 --- a/docs/quickstart.mkd +++ b/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 diff --git a/hamper.conf.dist b/hamper.conf.dist index 2fdf85d..bffd840 100644 --- a/hamper.conf.dist +++ b/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