Merge 5b9d8c1 into 5c3f60a

README.md

@@ -1,6 +1,6 @@
 # Ops Droid
 
-[![Build Status](https://travis-ci.org/opsdroid/opsdroid.svg?branch=master)](https://travis-ci.org/opsdroid/opsdroid) [![Coverage Status](https://coveralls.io/repos/github/opsdroid/opsdroid/badge.svg?branch=master)](https://coveralls.io/github/opsdroid/opsdroid?branch=master) [![Docker Image](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/r/opsdroid/opsdroid/) [![Documentation Status](https://readthedocs.org/projects/opsdroid/badge/?version=latest)](http://opsdroid.readthedocs.io/en/latest/?badge=latest)
+[![Build Status](https://travis-ci.org/opsdroid/opsdroid.svg?branch=master)](https://travis-ci.org/opsdroid/opsdroid) [![Coverage Status](https://coveralls.io/repos/github/opsdroid/opsdroid/badge.svg?branch=master)](https://coveralls.io/github/opsdroid/opsdroid?branch=master) [![Docker Image](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/r/opsdroid/opsdroid/) [![Docker Layers](https://images.microbadger.com/badges/image/opsdroid/opsdroid.svg)](https://microbadger.com/#/images/opsdroid/opsdroid) [![Documentation Status](https://readthedocs.org/projects/opsdroid/badge/?version=latest)](http://opsdroid.readthedocs.io/en/latest/?badge=latest)
 
 
 An open source python chat-ops bot

docs/configuration-reference.md

@@ -0,0 +1,113 @@
+# Configuration reference
+
+## Config file
+
+For configuration you simply need to create a single YAML file named `configuration.yaml`. When you run opsdroid it will look for the file in the following places in order:
+
+ * `./configuration.yaml`
+ * `~/.opsdroid/configuration.yaml`
+ * `/etc/opsdroid/configuration.yaml`
+
+The opsdroid project itself is very simple and requires modules to give it functionality. In your configuration file you must specify the connector, skill and database* modules you wish to use and any options they may require.
+
+**Connectors** are modules for connecting opsdroid to your specific chat service. **Skills** are modules which define what actions opsdroid should perform based on different chat messages. **Database** modules connect opsdroid to your chosen database and allows skills to store information between messages.
+
+## Reference
+
+### `connectors`
+
+Connector modules which are installed and connect opsdroid to a specific chat service.
+
+_Config options of the connectors themselves differ between connectors, see the connector documentation for details._
+
+```yaml
+connectors:
+
+  slack:
+    token: "mysecretslacktoken"
+
+  # conceptual connector
+  twitter:
+    oauth_key: "myoauthkey"
+    secret_key: "myoauthsecret"
+```
+
+See [module options](#module-options) for installing custom connectors.
+
+### `databases`
+
+Database modules which connect opsdroid to a persistent data storage service.
+
+Skills can store data in opsdroid's "memory", this is a dictionary which can be persisted in an external database.
+
+_Config options of the databases themselves differ between databases, see the database documentation for details._
+
+```yaml
+databases:
+  mongo:
+    host: "mymongohost.mycompany.com"
+    port: "27017"
+    database: "opsdroid"
+```
+
+See [module options](#module-options) for installing custom databases.
+
+### `logging`
+
+Set the logging level of opsdroid.
+
+All python logging levels are available in opsdroid. `logging` can be set to `debug`, `info`, `warning`, `error` and `critical`.
+
+```yaml
+logging: debug
+
+connectors:
+  shell:
+
+skills:
+  hello:
+  seen:
+```
+
+### `skills`
+
+Skill modules which add functionality to opsdroid.
+
+_Config options of the skills themselves differ between skills, see the skill documentation for details._
+
+```yaml
+skills:
+  hello:
+  seen:
+```
+
+See [module options](#module-options) for installing custom skills.
+
+## Module options
+
+All modules are installed from git repositories. By default if no additional options are specified opsdroid will look for the repository at `https://github.com/opsdroid/<moduletype>-<modulename>.git`.
+
+However if you wish to install a module from a different location you can specify the some more options.
+
+### `repo`
+
+A git url to install the module from.
+
+```yaml
+connectors:
+  slack:
+    token: "mysecretslacktoken"
+  mynewconnector:
+    repo: https://github.com/username/myconnector.git
+```
+
+### `no-cache`
+
+Set this to do a fresh git clone of the module whenever you start opsdroid.
+
+```yaml
+databases:
+  mongodb:
+    repo: https://github.com/username/mymongofork.git
+    no-cache: true
+```

docs/contributing.md

@@ -0,0 +1,57 @@
+# Contributing to the project
+
+Contributing to the opsdroid ecosystem is strongly encouraged. You can do this by creating modules to be used by opsdroid or by contributing to the project itself.
+
+## Workflow
+
+All contributors to the project, including [jacobtomlinson](https://github.com/jacobtomlinson), contribute using the following process:
+
+ * Fork the main project to your own account
+ * Work on your changes on a feature branch
+ * Create a pull request back to the main project
+ * Tests and test coverage will be checked automatically
+ * A project maintainer will review and merge the pull request
+
+## Developing
+
+```shell
+# clone the repo
+git clone https://github.com/opsdroid/opsdroid.git
+cd opsdroid
+
+# install project dependancies
+pip install -r requirements.txt
+
+# run opsdroid
+python -m opsdroid
+```
+
+Running the tests
+
+```shell
+# install test runner
+pip install -U tox
+
+# run tests
+tox
+```
+
+
+## Developing in containers
+
+Developing in containers can be a great way to ensure that opsdroid will run in a clean python environment and that all dependancies are captured.
+
+```shell
+# build the container
+docker build -t opsdroid/opsdroid:myfeature .
+
+# run opsdroid
+docker run --rm -ti -v $(pwd):/usr/src/app opsdroid/opsdroid:myfeature
+```
+
+Running the tests
+
+```shell
+# run tests
+docker run --rm -ti -v $(pwd):/usr/src/app opsdroid/opsdroid:myfeature tox
+```

docs/extending/connectors.md

@@ -0,0 +1,3 @@
+# Creating a connector
+
+To do...

docs/extending/databases.md

@@ -0,0 +1,3 @@
+# Creating a database
+
+To do

docs/extending/skills.md

@@ -0,0 +1,103 @@
+# Creating skills
+
+Like all opsdroid modules skills are installed as a git repository. However skills are designed to be simpler than other modules to ensure that it is easy to get started.
+
+To create a skill you need to create a single python file in your repository with the same name as the skill repository. For example the skill `hello` has a single file called `hello.py`.
+
+Within this file should be functions which are decorated with an opsdroid skill function to let opsdroid know when to trigger the skill. Let's get started with an example.
+
+## Hello world
+
+```python
+from opsdroid.skills import match_regex
+
+@match_regex('hi')
+def hello(opsdroid, message):
+    message.respond('Hey')
+```
+
+In this example we are importing the `match_regex` decorator from the opsdroid skills library. We are then using it to decorate a simple hello world function.
+
+The decorator takes a regular expression to match against the message received from the connector. In this case we are checking to see if the message from the user is "hi".
+
+If the message matches the regular expression then the decorated function is called. As arguments opsdroid will pass a pointer to itself along with a Message object containing information about the message from the user.
+
+## Message object
+
+The message object passed to the skill function is an instance of the opsdroid Message class which has the following properties and methods.
+
+### `text`
+
+A _string_ containing the message from the user.
+
+### `user`
+
+A _string_ containing the username of the user who wrote the message.
+
+### `room`
+
+A _string_ containing the name of the room or chat channel the message was sent in.
+
+### `regex`
+
+A _[re match object](https://docs.python.org/2/library/re.html#re.MatchObject)_ for the regular expression the message was matched against.
+
+### `connector`
+
+A pointer to the opsdroid _connector object_ which receieved the message.
+
+### `respond(text)`
+
+A method which responds to the message in the same room using the same connector that it was received.
+
+## Persisting data
+
+opsdroid has a memory class which can be used to persist data between different connectors (which run in different process forks) and between restarts of the application.
+
+The data can be accessed via the `memory` property of the `opsdroid` pointer which is passed to the skill function. The `memory` object has the following methods.
+
+### `get(key)`
+
+Returns an object from the memory for the key provided.
+
+### `put(key, object)`
+
+Stores the object provided for a specific key.
+
+### Example
+
+```python
+from opsdroid.skills import match_regex
+
+@match_regex(r'remember (.*)')
+def remember(opsdroid, message):
+    remember = message.regex.group(1)
+    opsdroid.memory.put("remember", remember)
+    message.respond("OK I'll remember that")
+
+@match_regex(r'remind me')
+def remember(opsdroid, message):
+    message.respond(
+      opsdroid.memory.get("remember")
+    )
+```
+
+In the above example we have defined two skill functions. The first takes whatever the user says after the work "remember" and stores it in the database.
+
+The second retrieves and prints out that text when the user says "remind me".
+
+## Setup
+
+If your skill requires any setup to be done when opsdroid is started you can create a method simple called `setup` which takes a pointer to opsdroid as it's only argument.
+
+```python
+def setup(opsdroid):
+  # do some setup stuff here
+```
+
+## Example modules
+
+See the following official modules for examples:
+
+ * [hello](https://github.com/opsdroid/skill-hello) - A simple hello world skill.
+ * [seen](https://github.com/opsdroid/skill-seen) - Makes use of opsdroid memory.

docs/getting-started.md

@@ -0,0 +1,85 @@
+# Getting started
+
+## Installation
+
+You can simply install opsdroid using `pip`.
+
+```
+pip3 install opsdroid
+```
+
+Or you can use the official docker image.
+
+```
+docker pull opsdroid/opsdroid:latest
+```
+
+## Configuration
+
+For configuration you simply need to create a single YAML file named `configuration.yaml`. When you run opsdroid it will look for the file in the following places in order:
+
+ * `./configuration.yaml`
+ * `~/.opsdroid/configuration.yaml`
+ * `/etc/opsdroid/configuration.yaml`
+
+The opsdroid project itself is very simple and requires modules to give it functionality. In your configuration file you must specify the connector, skill and database* modules you wish to use and any options they may require.
+
+**Connectors** are modules for connecting opsdroid to your specific chat service. **Skills** are modules which define what actions opsdroid should perform based on different chat messages. **Database** modules connect opsdroid to your chosen database and allows skills to store information between messages.
+
+For example a simple barebones configuration would look like:
+
+```yaml
+connectors:
+  shell:
+
+skills:
+  hello:
+```
+
+This tells opsdroid to use the [shell connector](https://github.com/opsdroid/connector-shell) and [hello skill](https://github.com/opsdroid/skill-hello) from the official module library.
+
+In opsdroid all modules are git repositories which will be cloned locally the first time they are used. By default if you do not specify a repository opsdroid will look at `https://github.com/opsdroid/<moduletype>-<modulename>.git` for the repository. Therefore in the above configuration the `connector-shell` and `skill-hello` repositories were pulled from the opsdroid organisation on GitHub.
+
+You are of course encouraged to write your own modules and make them available on GitHub or any other repository host which is accessible by your opsdroid installation.
+
+A more advanced config would like similar to the following:
+
+```yaml
+connectors:
+  slack:
+    token: "mysecretslacktoken"
+
+databases:
+  mongo:
+    host: "mymongohost.mycompany.com"
+    port: "27017"
+    database: "opsdroid"
+
+skills:
+  hello:
+  seen:
+  myawesomeskill:
+    repo: "https://github.com/username/myawesomeskill.git"
+```
+
+In this configuration we are using the [slack connector](https://github.com/opsdroid/connector-slack) with a slack [auth token](https://api.slack.com/tokens) supplied, a [mongo database](https://github.com/opsdroid/database-mongo) connection for persisting data, `hello` and `seen` skills from the official repos and finally a custom skill hosted on GitHub.
+
+Configuration options such as the `token` in the slack connector or the `host`, `port` and `database` options in the mongo database are specific to those modules. Ensure you check each module's required configuration items before you use them.
+
+## Running
+
+If you installed opsdroid using `pip` and have created your `configuration.yaml` file in the correct place you can simple start it by running:
+
+```
+opsdroid
+```
+
+If you are using the opsdroid docker image then ensure you add your configuration as a volume and run the container.
+
+```
+docker run --rm -v /path/to/configuration.yaml:/etc/configuration.yaml:ro opsdroid/opsdroid:latest
+```
+
+-------
+
+_\* databases are optional, however bot memory will not persist between different connectors or system reboots without one_