Add some basic documentation

README.md

@@ -4,9 +4,9 @@ Yaboli (**Y**et **A**nother **Bo**t **Li**brary) is a Python library for
 creating bots for [euphoria.io](https://euphoria.io).
 
 - [Changelog](CHANGELOG.md)
+- [Documentation](docs/index.md)
 
-Soon, markdown files containing documentation and troubleshooting info will be
-available.
+Soon, markdown files containing troubleshooting info will be available.
 
 ## Installation
 
@@ -62,7 +62,6 @@ i. e. the text between the end of the "!echo" and the end of the whole message.
 - [ ] cookie support
 - [ ] fancy argument parsing
 - [ ] document new classes (docstrings, maybe comments)
-- [ ] write project readme
 - [ ] write examples
 - [ ] make yaboli package play nice with mypy
 - [x] implement !uptime for proper botrulez conformity
@@ -74,3 +73,4 @@ i. e. the text between the end of the "!echo" and the end of the whole message.
 - [x] package in a distutils-compatible way (users should be able to install
   yaboli using `pip install git+https://github.com/Garmelon/yaboli`)
 - [x] implement !restart
+- [x] write project readme

docs/index.md

@@ -0,0 +1,79 @@
+# Index for yaboli docs
+
+Links to specific sections will be added here.
+
+## Library structure overview
+
+### Message, Session
+
+A `Message` represents a single message. It contains all the fields [specified
+in the API](http://api.euphoria.io/#message), in addition to a few utility
+functions.
+
+Similar to a `Message`, a `Session` represents a session and also contains
+almost all the fields [specified in the
+API](http://api.euphoria.io/#sessionview), in addition to a few utility
+functions.
+
+`Message`s and `Session`s also both contain the name of the room they
+originated from.
+
+### Room
+
+A `Room` represents a single connection to a room on euphoria. It tries to keep
+connected and reconnects if it loses connection. When connecting and
+reconnecting, it automatically authenticates and sets a nick.
+
+In addition, a `Room` also keeps track of its own session and the sessions of
+all other people and bots connected to the room. It doesn't remember any
+messages though, since no "correct" solution to do that exists and the method
+depends on the design of the bot using the `Room` (keeping the last few
+messages in memory, storing messages in a database etc.).
+
+### LiveMessage, LiveSession
+
+`LiveMessage`s and `LiveSession`s function the same as `Message`s and
+`Session`s, with the difference that they contain the `Room` object they
+originated from, instead of just a room name. This allows them to also include
+a few convenience functions, like `Message.reply`.
+
+Usually, `Room`s and `Client`s (and thus `Bot`s) will pass `LiveMessage`s and
+`LiveSession`s instead of their `Message` and `Session` counterparts.
+
+### Client
+
+A `Client` may be connected to a few rooms on euphoria and thus manages a few
+`Room` objects. It has functions for joining and leaving rooms on euphoria, and
+it can also be connected to the same room multiple times (resulting in multiple
+`Room` objects).
+
+The `Client` has a few `on_<event>` functions (e. g. `on_message`, `on_join`)
+that are triggered by events in any of the `Room` objects it manages. This
+allows a `Client` to react to various things happening in its `Room`s.
+
+### Bot
+
+A `Bot` is a client that:
+
+- is configured using a config file
+- reacts to commands using a command system
+- implements most commands specified in the
+  [botrulez](https://github.com/jedevc/botrulez)
+
+The config file includes the bot's default nick, initial rooms and bot-specific
+configuration. Upon starting a `Bot`, it joins the rooms specified in the
+config, setting its nick to the default nick.
+
+The command system can react to general and specific commands as specified in
+the botrulez, and can parse command arguments with or without bash-style string
+escaping, and with or without unix-like syntax (flags and optional arguments).
+
+### Module, ModuleBot
+
+A `Module` is a `Bot` that can also be used as a module in a `ModuleBot`. This
+is like combining multiple bots into a single bot.
+
+The most notable differences are the new `DESCRIPTION` and `standalone` fields.
+The `DESCRIPTION` field contains a short description of the module, whereas the
+`standalone` field answers the question whether the `Module` is being run as
+standalone bot or part of a `ModuleBot`.