Another pass on the docs

Added a TOC!

README.md

@@ -12,13 +12,32 @@ A friendly lightweight wrapper around
 goal is to make writing and running XMPP bots easy and fun. `xbotlib` is a
 [single file implementation](./xbotlib.py) which can easily be understood and
 extended. It provides a small API surface which reflects the `slixmpp` way of
-doing things.
+doing things. The `xbotlib` source code and ideas are largely
-
-The `xbotlib` source code and ideas are largely
 borrowed/stolen/adapted/reimagined from the XMPP bot experiments that have gone
 on and are still going on in
 [Varia](https://git.vvvvvvaria.org/explore/repos?tab=&sort=recentupdate&q=bots).
 
+- [Install](#install)
+- [Example](#example)
+- [API Reference](#api-reference)
+  - [Bot.direct(message)](#botdirect-message-)
+  - [Bot.group(message)](#botgroup-message-)
+  - [SimpleMessage](#simplemessage)
+- [Documenting your bot](#documenting-your-bot)
+- [Commands](#commands)
+- [Avatars](#avatars)
+- [Configure your bot](#configure-your-bot)
+  - [Using the `.conf` configuration file](#using-the--conf--configuration-file)
+  - [Using the command-line interface](#using-the-command-line-interface)
+  - [Using the environment](#using-the-environment)
+- [Persistent storage](#persistent-storage)
+- [Redis key/value storage](#redis-key-value-storage)
+- [Loading Plugins](#loading-plugins)
+- [Deploy your bots](#deploy-your-bots)
+- [Roadmap](#roadmap)
+- [Changes](#changes)
+- [license](#license)
+
 ## Install
 
 ```sh
@@ -27,10 +46,10 @@ $ pip install xbotlib
 
 ## Example
 
-Put the following in a `echo.py` file.
+Put the following in a `echo.py` file. `xbotlib` provides a number of example
-
+bots which you can use to get moving fast and try things out. This bot is the
-`xbotlib` provides a number of example bots which you can use to get moving
+simplest one we have: it simply echoes back whatever message you send it. It is
-fast and try things out.
+an easy way to get started.
 
 ```python
 from xbotlib import EchoBot
@@ -39,36 +58,48 @@ EchotBot()
 ```
 
 And then `python echo.py`. You will be asked a few questions in order to load
-the account details that your bot will be using. This will generate a
+the account details that your bot will be using. This will generate an
 `echobot.conf` file in the same working directory for further use. See the
 [configuration](#configure-your-bot) section for more.
 
-Here's the code for the `EchoBot`.
+Here's the annotated source for the `EchoBot`.
 
 ```python
+from xbotlib import Bot
+
+# Define a class and inherit from xbotlib.Bot
 class EchoBot(Bot):
+
+    # Respond to direct messages using the `direct` function
     def direct(self, message):
+        # Send back the entire text of the message using `message.text`
         self.reply(message.text, to=message.sender)
+
+    # Respond to group chat messages using the `group` function
     def group(self, message):
+        # Send back the content of the message. In this case if we were
+        # sent `echobot, hoi` in the group chat then the `message.content`
+        # would be equal to `hoi`
         self.reply(message.content, room=message.room)
 ```
 
 Read more in the [API reference](#api-reference) for how to write your own bots.
 
-## All examples
+A numer of other example bots are provided.
 
 - **EchoBot**: Sends back what you sent it
 - **WhisperBot**: Anonymous whispering in group chats
 - **GlossBot**: Building a shared glossary together
 
-See [xbotlib.py](./xbotlib.py) for all example bots.
+See [xbotlib.py](./xbotlib.py) for the sources.
 
 ## API Reference
 
 When writing your own bot, you always sub-class the `Bot` class provided from
 `xbotlib`. Then if you want to respond to a direct message, you write a
 [direct](#botdirectmessage) function. If you want to respond to a group chat
-message, you write a [group](#botgroupmessage) function.
+message, you write a [group](#botgroupmessage) function. That's it for the
+basics.
 
 ### Bot.direct(message)
 
@@ -113,7 +144,9 @@ See more in the [commands](#commands) section on how to use this.
 
 ## Commands
 
-Using `@<command>` in direct messages and `<nick>, @<command>` in group chats,
+Using `@<command>` in direct messages and `<nick>, @<command>` (the `,` is
+optional, anything will be accepted here and there doesn't seem to be a
+consensus on what is most common way to "at" another user in XMPP) in group chats,
 here are the supported commands.
 
 - **@uptime**: how long the bot has been running
@@ -133,7 +166,10 @@ of `64` and a width of `64` pixels each.
 
 ## Configure your bot
 
-All the ways you can pass configuration details to your bot.
+All the ways you can pass configuration details to your bot. There are three
+ways to configure your bot, the configuration file, command-line interface and
+the environment. Use whichever one suits you best. The values are loaded in the
+following order: command-line > configuration file > environment.
 
 ### Using the `.conf` configuration file
 
@@ -156,6 +192,30 @@ rooms = test@muc.example.com
 Every bot accepts a number of comand-line arguments to load configuration. You
 can use the `--help` option to see what is available (e.g. `python bot.py --help`).
 
+```
+usage: bot.py [-h] [-d] [-a ACCOUNT] [-p PASSWORD] [-n NICK]
+              [-av AVATAR] [-ru REDIS_URL] [-r ROOMS [ROOMS ...]]
+              [--no-auto-join]
+
+XMPP bots for humans
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d, --debug           Enable verbose debug logs
+  -a ACCOUNT, --account ACCOUNT
+                        Account for the bot account
+  -p PASSWORD, --password PASSWORD
+                        Password for the bot account
+  -n NICK, --nick NICK  Nickname for the bot account
+  -av AVATAR, --avatar AVATAR
+                        Avatar for the bot account
+  -ru REDIS_URL, --redis-url REDIS_URL
+                        Redis storage connection URL
+  -r ROOMS [ROOMS ...], --rooms ROOMS [ROOMS ...]
+                        Rooms to automatically join
+  --no-auto-join        Disable automatically joining rooms when invited
+```
+
 ### Using the environment
 
 `xbotlib` will try to read the following configuration values from the
@@ -177,12 +237,14 @@ deployments.
 
 `xbotlib` supports using [Redis](https://redis.io/) as a storage back-end. It
 is simple to work with because the interface is exactly like a dictionary. You
-can quickly run Redis locally using
+can quickly run Redis locally using [Docker](https://docs.docker.com/engine/install/debian/)
-[Docker](https://docs.docker.com/engine/install/debian/) or if you're on a
+(`docker run --network=host --name redis -d redis`) or if you're on a Debian system you can
-Debian system you can also `sudo apt install -y redis`.
+also `sudo apt install -y redis`.
+
+You can configure the connection URL using the command-line interface,
+configuration or environment. Here is an example using the environment.
 
 ```bash
-$ docker run --network=host --name redis -d redis
 $ export XBOT_REDIS_URL=redis://localhost:6379/0
 ```
 

xbotlib.py

@@ -174,7 +174,7 @@ class Bot(ClientXMPP):
             "-a",
             "--account",
             dest="account",
-            help="Account for the bot account (foo@example.com)",
+            help="Account for the bot account",
         )
         self.parser.add_argument(
             "-p",