Merge eebab3c into 5c3f60a

README.md

@@ -1,6 +1,6 @@
-# Ops Droid
+![opsdroid](https://github.com/opsdroid/style-guidelines/raw/master/logos/logo-wide-light.png)
 
-[![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,52 @@
+# Creating a connector
+
+Connectors are a class which extends the base opsdroid Connector. The class has two mandatory methods, `connect` and `respond`.
+
+#### connect
+*connect* is a method which connects to a specific chat service and retrieves messages from it. Each message is formatted into an opsdroid Message object and then parsed. This method should block the thread with an infinite loop.
+
+#### respond
+*respond* will take a Message object and return the contents to the chat service.
+
+```python
+
+import time
+
+# We recommend you use the official library
+# for your chat service and import it here
+import chatlibrary
+
+# Import opsdroid dependancies
+from opsdroid.connector import Connector
+from opsdroid.message import Message
+
+
+class MyConnector(Connector):
+
+  def connect(self, opsdroid):
+    # Create connection object with chat library
+    self.connection = chatlibrary.connect()
+
+    while True:
+      # Get raw message from chat
+      raw_message = self.connection.get_next_message()
+
+      # Convert to opsdroid Message object
+      #
+      # Message objects take a pointer to the connector to
+      # allow the skills to call the respond method
+      message = Message(raw_message.text, raw_message.user,
+                        raw_message.room, self)
+
+      # Parse the message with opsdroid
+      opsdroid.parse(message)
+
+      # Sleep before processing next message
+      time.sleep(1)
+
+  def respond(self, message):
+    # Send message.text back to the chat service
+    self.connection.send(raw_message.text, raw_message.user,
+                         raw_message.room)
+
+```

docs/extending/databases.md

@@ -0,0 +1,42 @@
+# Creating a database
+
+Database classes are used to persist key/value pairs in a database. Values can be a complex object such as an array or a dictionary.
+
+The class has three mandatory methods, `connect`, `put` and `get`.
+
+#### connect
+*connect* should initialise a connection to a database and store that connection object as a property of the database module instance.
+
+#### put
+*put* stores an object for a given key.
+
+#### get
+*get* returns an object for a given key. The object which is returned should be equivalent to the object which was stored.
+
+```python
+# We recommend you use the official library
+# for your database and import it here
+import databaselibrary
+
+# Import opsdroid dependancies
+from opsdroid.database import Database
+
+
+class MyDatabase(Database):
+
+  def connect(self, opsdroid):
+    # Create connection object for database
+    self.connection = databaselibrary.connect()
+
+  def put(self, key, value):
+    # Insert the object into the database
+    response = self.connection.insert(key, value)
+
+    # Return a bool for whether the insert was successful
+    return response.success
+
+  def get(self, key):
+    # Get the object from the database and return it
+    return self.connection.find(key)
+
+```

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.