Documentation time!

docs/index.md

@@ -115,7 +115,7 @@ Eventually, you'll reach this screen of joy.  Now, it's time to play!
 
 #### Testing will out
 
-Once your will is up and running, hop into any of your hipchat rooms, and say hello!
+Once your will is up and running, hop into any of your chat rooms, and say hello!
 
 `@will hi`
 

docs/platforms/ubuntu.md

@@ -0,0 +1,129 @@
+<img align="right" src="img/will-head.png" alt="Will's smiling face" title="Will's smiling face" class="will_head" />
+
+
+# Meet Will
+
+Will is the friendliest, easiest-to-teach bot you've ever used.  He works on hipchat, in rooms and 1-1 chats.
+
+He makes teaching your chat bot this simple:
+
+```
+@respond_to("hi")
+def say_hello(self, message):
+    self.say("oh, hello!")
+```
+
+Lots of batteries are included, and you can get your own will up and running in a couple of minutes.  
+
+Will started by [Steven Skoczen](http://www.inkandfeet.com), and has been [contributed to by lots of folks](improve.md#shoulders).
+
+Check out the quickstart below!
+
+<div style="width:100%;clear:both;"></div>
+
+# Quickstart
+
+Here's how to set up your system and get will running.  If you already write python, it'll probably take less than 5 minutes.
+
+---
+
+## Install prerequisites
+
+Will doesn't need much, just python and a place to store things.
+
+Will can store stuff in Redis, Couchbase, or local storage.  Our recommended backend is redis, and we'll describe getting it set up below. [Information on using Couchbase or local storage is here](deploy.md#Storage-Backends).
+
+#### Install redis > 2.4
+
+Official documentation is at [redis.io](http://redis.io/).
+
+If you're on Mac OS X, and using [homebrew](http://brew.sh/), you can simply:
+
+```bash
+brew install redis
+```
+
+On a Redhat (RHEL, Centos, Fedora) machine you can:
+
+```bash
+sudo yum install redis
+sudo service redis enable
+sudo service redis start
+```
+
+On a Debian (Ubuntu, Mint, KNOPPIX) machine to properly install follow the [Redis Quickstart](http://redis.io/topics/quickstart). But you can start more quickly with:
+
+```bash
+sudo apt-get install redis-server
+redis-server
+```
+
+#### Install python > 2.6
+
+Most modern operating systems (Mac OS X, Linux, BSDs, etc) ship with python installed, but if you don't have it, all the info is at [python.org](https://www.python.org/).
+
+#### Install virtualenv
+
+Virtualenv is a tool that lets you keep different python projects separate. It is highly recommended for will (and all other python development!)
+
+The python guide has [a great tutorial on virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/), if you don't already have it running.  I'd recommend installing the excellent `virtualenvwrapper` library it mentions as well.
+
+#### Set up a virtualenv for will
+
+If you are using virtualenv wrapper:
+
+```bash
+$ mkproject my_will
+# ... some output, setting up the virtualenv
+$ workon my_will
+(my_will) $ 
+```
+
+You're now all ready to install will!
+
+
+
+## Get will running locally
+
+#### Setting up the project
+
+Installing will is simple easy.  Ready? Go!
+
+From your virtualenv and the folder you want to set up your will in,
+
+```bash
+(my_will) $ pip install will
+# ... output from a bunch of pip libraries installing
+
+(my_will) $ generate_will_project
+# ... output from will making your new project
+
+(my_will) $ ./run_will.py
+# .. the magic begins
+```
+
+That's it!  
+
+Note that the first time you run, you'll probably be missing some configuration. That's OK - `run_will` will check your environment, and walk you through getting and setting any necessary config.  We'll go through the nitty-gritty later, but if you have any odd setup problems, look in `config.py` - that's where all of the non-sensitive data is stored.
+
+![Uninitialized Environment output](img/uninitialized_env.gif)
+This is totally normal output.
+
+Eventually, you'll reach this screen of joy.  Now, it's time to play!
+
+![Screen of Joy](img/screen_of_joy.gif)
+
+#### Testing will out
+
+Once your will is up and running, hop into any of your hipchat rooms, and say hello!
+
+`@will hi`
+
+![Hi, Will](img/hi.gif)
+
+`@will help`
+
+![Help, will](img/help.gif)
+
+You're up and running - now it's time to [teach your will a few things](plugins/basics.md)!
+

docs/platforms/upgrading.md

@@ -0,0 +1,131 @@
+# Upgrading from Will 1.0
+
+Will 2.0 is finally here, and its main goal was to free people using Will from being locked into a single chat provider, and add some more flexibility to his brain.  You can read the [release announcement](https://heywill.io/will2) for a bit more context!
+
+While Will has picked up a bunch of features and improvements in 2.0, we've aimed to keep him backwards-compatable with 1.x and 0.x releases.  If you weren't using any undocumented internal methods, upgrading should be as easy as:
+
+```
+pip install --upgrade will
+```
+
+From there, you can just `./run_will.py`, and things should Just Work.
+
+You will, however, see a lot of output from Will, telling you that some names have changed, and asking you to update them in your config.py when you have time.  You can either just follow those instructions, or the guide below.
+
+## Updating your settings to Will 2
+
+There are two big changes in the settings from Will 1 to Will 2, and both come from the fact that will now supports multiple chat backends.
+
+### 1. Move to the new IO_BACKENDS syntax
+
+If you're just planning to continue using HipChat, we'd recommend that you add this to your config.py:
+
+IO_BACKENDS = "
+    "will.backends.io_adapters.hipchat",
+    "will.backends.io_adapters.shell",
+#   "will.backends.io_adapters.slack",
+#   "will.backends.io_adapters.rocketchat",
+]
+
+That will enable the HipChat and local shell stdin/stdout backend, for easy testing.  If you want to also bring Will into a Slack or Rocket.Chat room in the future, just uncomment the backend!
+
+### 2. Update the HipChat tokens to be namespaced.  
+
+You'll see this starting up, but when you have time, update your tokens as follows:  (If you're using `WILL_` environment variables, please add the `WILL_` as needed:)
+
+`USERNAME` becomes `HIPCHAT_USERNAME`
+
+`TOKEN` becomes `HIPCHAT_V1_TOKEN`
+
+`V2_TOKEN` becomes `HIPCHAT_V2_TOKEN`
+
+`DEFAULT_ROOM` becomes `HIPCHAT_DEFAULT_ROOM`
+
+`HANDLE` should be removed, as it's now pulled live from the HipChat servers and not used.
+
+`NAME` should be removed, as it's now pulled live from the HipChat servers and not used.
+
+`PASSWORD` becomes `HIPCHAT_PASSWORD`
+
+`ROOMS` becomes `HIPCHAT_ROOMS`
+
+
+### 3. If you're not using redis for storage, set it up for the pubsub backend.
+
+At the moment, Redis is the only working pubsub backend, though ZeroMQ support is in the works, and we're looking to add a pure-python backend shortly.
+
+
+### 4. Set SECRET_KEY.
+
+Will now encrypts all messages on the pubsub wire and in storage by default.  Without a SECRET_KEY set, he'll auto-generate one based on the machine MAC address, but this isn't a perfect solution, and will mean that he can't access his storage if there are hardware changes (or he's running in a virtualized environment.)
+
+Please set `SECRET_KEY` as soon as possible.
+
+The recommended way is to set it as an environmental variable, `WILL_SECRET_KEY`, in an environment that is secured and you trust.  Any string will work, and entropy is good. 
+
+
+### 5. Set the new, Will 2.0 configuration and settings to your liking.
+
+Will 2 ships with bunch of new features, and though we've provided sensible defaults, if you'd like, you can update your `config.py` with your preferences.
+
+The simplest way to see everything is to have Will generate a `config.py.dist` that you can use for comparison:
+
+`generate_will_project --config_dist_only`
+
+It's worth reading through the new `config.py`, but here's a few areas specifically worth a look:
+
+#### Platform and Decision-making
+
+As mentioned above, there are now multiple IO mediums and platforms that Will can communicate on (and more are coming soon).  Here's all the options
+
+```
+IO_BACKENDS = [
+    "will.backends.io_adapters.slack",
+    "will.backends.io_adapters.hipchat",
+    "will.backends.io_adapters.rocketchat",
+    "will.backends.io_adapters.shell",
+]
+```
+
+
+Will 2 also comes with pluggable brains - split into Analysis, Generation, and Execution backends.  The defaults are solid and behave similarly to Will 1.0 (the only difference is a high-confidence fuzzy matching engine), but if you're interested in making your Will more flexible, or adding more context to his responses, building custom backends is easy.
+
+Here's all of the options, with the defaults uncommented.   It's worth pulling this into your `config.py`.
+
+```
+# Backends to analyze messages and generate useful metadata
+ANALYZE_BACKENDS = [
+    "will.backends.analysis.nothing",
+    "will.backends.analysis.history",
+]
+
+# Backends to generate possible actions, and metadata about them.
+GENERATION_BACKENDS = [
+    # "will.backends.generation.fuzzy_best_match",
+    "will.backends.generation.fuzzy_all_matches",
+    "will.backends.generation.strict_regex",
+]
+
+# The "decision making" backends that look among the generated choices,
+# and decide which to follow. Backends are executed in order, and any
+# backend can stop further evaluation.
+EXECUTION_BACKENDS = [
+    "will.backends.execution.best_score",
+    # "will.backends.execution.all",
+]
+```
+
+There are also a few settings to tweak things like the fuzzy logic.  These have sensible defaults, but you can tweak them to your liking.
+
+```
+# Confidence fuzzy generation backends require before Will responds
+# https://pypi.python.org/pypi/fuzzywuzzy
+FUZZY_MINIMUM_MATCH_CONFIDENCE = 90  # Defaults to 90%
+FUZZY_REGEX_ALLOWABLE_ERRORS = 3
+```
+
+### That's it - let us know how it goes!
+
+That's all you really need to know to flip the switch to Will 2.0.  As there's a lot of new stuff in this release, it's possible that some bugs have slipped through the cracks.  Please submit anything you find, no matter how small, [into the github issue tracker](https://github.com/skoczen/will/issues).  We'll be active in fixing things ASAP and helping if you're stuck.
+
+Thanks for using Will, and for going through the big upgrade!  We're excited about what the future holds, and happy to get your bots free from platform lock-in.

will/scripts/config.py.dist

@@ -67,6 +67,13 @@ PLUGIN_BLACKLIST = [
     "will.plugins.devops.pagerduty",  # Because it requires a PAGERDUTY_SUBDOMAIN and PAGERDUTY_API_KEY key
 ]
 
+# A secret key, used to namespace this instance of will and secure pubsub contents.
+# Do *NOT* keep it in config.py.  *DO* set it in the environment as WILL_SECRET_KEY,
+# in a secured session. If a SECRET_KEY is not set, one will be auto-generated,
+# but it may limit Will to reading data from this excecution only, and may not work
+# on virtualized machines, or machines with many or changing MAC addresses
+# SECRET_KEY = "DXQnJ2eHD6k2w3DvBTstN6kw9d9N4CeCLbjoK"
+
 # ------------------------------------------------------------------------------------
 # Platform and Decision-making
 # ------------------------------------------------------------------------------------
@@ -201,14 +208,6 @@ FUZZY_REGEX_ALLOWABLE_ERRORS = 3
 # Increasing the value will make will slower, but consume fewer resources.
 # EVENT_LOOP_INTERVAL = 0.025
 
-# A secret key, used to namespace this instance of will and secure pubsub contents.
-# Do *NOT* keep it in config.py.  *DO* set it in the environment as WILL_SECRET_KEY,
-# in a secured session. If a SECRET_KEY is not set, one will be auto-generated,
-# but it may limit Will to reading data from this excecution only, and may not work
-# on virtualized machines, or machines with many or changing MAC addresses
-# SECRET_KEY = "DXQnJ2eHD6k2w3DvBTstN6kw9d9N4CeCLbjoK"
-
-
 # Turn up or down Will's logging level
 # LOGLEVEL = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
 # LOGLEVEL = "DEBUG"
@@ -218,7 +217,7 @@ FUZZY_REGEX_ALLOWABLE_ERRORS = 3
 
 # Turn on/off encryption in pub/sub and storage (default is on).
 # Causes a small speed bump, but secures messages in an untrusted environment.
-# ENABLE_INTERNAL_ENCRYPTION = False
+# ENABLE_INTERNAL_ENCRYPTION = True
 # ENCRYPTION_BACKEND = "aes"
 
 # Mailgun config, if you'd like will to send emails.