Add parser configuration to documentation (#502)

* Document parser configuration
(#477)

    Adds a parsers section in the configuration reference.

* Document parser config (#477)
    Added/moved the configuration info to the starting of each matcher file.

docs/configuration-reference.md

@@ -5,7 +5,8 @@
    - [Connector Modules](#connector-modules)
    - [Database Modules](#database-modules)
    - [Logging](#logging)
-   - [Installation Path](#installation-path) 
+   - [Installation Path](#installation-path)
+   - [Parsers](#parsers) 
    - [Skills](#skills)
    - [Time Zone](#time-zone)
    - [Language](#language)
@@ -179,6 +180,29 @@ skills:
   - name: seen
 ```
 
+### Parsers
+
+When writing skills for opsdroid there are multiple parsers you can use for matching messages to your functions.
+
+_Config options of the parsers themselves differ between parsers, see the parser/matcher documentation for details._
+
+```yaml
+parsers:
+  - name: regex
+    enabled: true
+
+# NLU parser
+  - name: rasanlu
+    url: http://localhost:5000
+    project: opsdroid
+    token: 85769fjoso084jd
+    min-score: 0.8
+```
+
+Some parsers will allow you to specify a min-score to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. You just need to add the required min-score under a parser in the configuration.yaml file.
+
+See the matchers section for more details.
+
 ### Skills
 
 Skill modules which add functionality to opsdroid.

docs/matchers/always.md

@@ -1,5 +1,11 @@
 # Always matcher
 
+## Configuring opsdroid
+
+The `always` matcher parses every message as it is always running. So it need not be configured explicitly.
+
+##
+
 The `always` matcher is a special case which simply always matches a skill to every single message that passes through opsdroid.
 
 When a message is parsed all skills are ranked by the parsers in order of how confident they are that the message is a match, and then the highest ranking skill is executed. The `always` matcher is useful if you are wanting to do something like keep track of the last time someone spoke, so you need the skill to execute on every message and you will never directly respond to a message.
@@ -13,4 +19,3 @@ from opsdroid.matchers import match_always
 async def keep_track(opsdroid, config, message):
     # Put message.user into a database along with a timestamp
 ```
-

docs/matchers/crontab.md

@@ -1,5 +1,17 @@
 # Crontab Matcher
 
+## Configuring opsdroid
+
+In order to enable crontab skills you must set the `enabled` paramater to true in the parsers section of the opsdroid configuration file.
+
+```yaml
+parsers:
+  - name: crontab
+    enabled: true
+```
+
+##
+
 The crontab matcher is a bit different to other matchers. This matcher doesn't take a message as an input, it takes a [cron timing](https://en.wikipedia.org/wiki/Cron) instead. It allows you to schedule skills to be called on an interval instead of being triggered by messages.
 
 ## Example

docs/matchers/dialogflow.md

@@ -1,5 +1,21 @@
 # Dialogflow Matcher (previously Api.ai)
 
+## Configuring opsdroid
+
+In order to enable Dialogflow skills you must specify an `access-key` for your bot (referred to as an agent in Dialogflow) in the matchers section of the opsdroid configuration file. You can find this `access-key` in your agent settings. Currently you may only register one agent per opsdroid instance to avoid making multiple API calls for every message.
+
+You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
+
+```yaml
+
+parsers:
+  - name: dialogflow
+    access-token: "exampleaccesstoken123"
+    min-score: 0.6
+```
+
+##
+
 [Dialogflow](https://dialogflow.com/) is an NLP API for matching strings to [intents](https://dialogflow.com/docs/intents) or [actions](https://dialogflow.com/docs/concept-actions). Intents are created on the Dialogflow website.
 
 ## Example 1
@@ -34,21 +50,6 @@ If you want to use Dialogflow in a different language other than English, all yo
 
 _Useful Links: [Languages Reference](https://dialogflow.com/docs/reference/language), [Multi-language Agents Reference](https://dialogflow.com/docs/multi-language)_
 
-
-## Configuring opsdroid
-
-In order to enable Dialogflow skills you must specify an `access-key` for your bot (referred to as an agent in Dialogflow) in the matchers section of the opsdroid configuration file. You can find this `access-key` in your agent settings. Currently you may only register one agent per opsdroid instance to avoid making multiple API calls for every message.
-
-You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
-
-```yaml
-
-parsers:
-  - name: dialogflow
-    access-token: "exampleaccesstoken123"
-    min-score: 0.6
-```
-
 ## Message object additional parameters
 
 ### `message.dialogflow`

docs/matchers/luis.ai.md

@@ -1,5 +1,21 @@
 # luis.ai Matcher
 
+## Configuring opsdroid
+
+In order to enable luis.ai skills you must specify an `appid` and `appkey` for your bot. You can further configure the bot by enabling `verbose` or setting a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
+
+```yaml
+
+parsers:
+   - name: luisai
+     appid: "<application-id>"
+     appkey: "<subscription-key>"
+     verbose: True
+     min-score: 0.6
+```
+
+##
+
 [luis.ai](https://www.luis.ai) is an NLP API for matching strings to [intents](https://docs.microsoft.com/en-us/azure/cognitive-services/LUIS/Home). Intents are created on the luis.ai website.
 
 ## Example 1
@@ -23,20 +39,6 @@ If you want to use LUIS in a different language other than English, you will nee
 
 _Note: "Each LUIS app has a unique app ID, and endpoint log." [Multi-language LUIS apps Reference](https://docs.microsoft.com/en-us/azure/cognitive-services/LUIS/luis-supported-languages)
 
-## Configuring opsdroid
-
-In order to enable luis.ai skills you must specify an `appid` and `appkey` for your bot. You can further configure the bot by enabling `verbose` or setting a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
-
-```yaml
-
-parsers:
-   - name: luisai
-     appid: "<application-id>"
-     appkey: "<subscription-key>"
-     verbose: True
-     min-score: 0.6
-```
-
 ## Message object additional parameters
 
 ### `message.luisai`

docs/matchers/rasanlu.md

@@ -1,4 +1,26 @@
-# Rasa NLU Matcher
+# Rasa NLU Matcher
+
+## Configuring opsdroid
+
+In order to enable Rasa NLU skills, you can tell opsdroid where to find your Rasa NLU instance in the parsers section of the opsdroid configuration file. You can set the `url` and `project` parameters which default to `http://localhost:5000` and `opsdroid` respectively.
+
+Projects in Rasa NLU are separate areas for training and storing your intent models. This is useful as you can have multiple instances of opesdroid (or even other applications) sharing one instance of Rasa NLU if you configure them with different project names.
+
+Rasa NLU gives you the option to set a password or `token` which must be provided when interacting with the API. You can optionally set this in the parser config too.
+
+You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
+
+```yaml
+
+parsers:
+  - name: rasanlu
+    url: http://localhost:5000
+    project: opsdroid
+    token: 85769fjoso084jd
+    min-score: 0.8
+```
+
+##
 
 [Rasa NLU](https://github.com/RasaHQ/rasa_nlu) is an open source tool for running your own NLP API for matching strings to [intents](https://rasahq.github.io/rasa_nlu/). This is the recommended parser if you have privacy concerns but want the power of a full NLU parsing engine.
 
@@ -62,26 +84,6 @@ Intents file (`intents.md`).
 
 The above skill would be called on any intent which has a name of `'ask-joke'`.
 
-## Configuring opsdroid
-
-In order to enable Rasa NLU skills, you can tell opsdroid where to find your Rasa NLU instance in the parsers section of the opsdroid configuration file. You can set the `url` and `project` parameters which default to `http://localhost:5000` and `opsdroid` respectively.
-
-Projects in Rasa NLU are separate areas for training and storing your intent models. This is useful as you can have multiple instances of opesdroid (or even other applications) sharing one instance of Rasa NLU if you configure them with different project names.
-
-Rasa NLU gives you the option to set a password or `token` which must be provided when interacting with the API. You can optionally set this in the parser config too.
-
-You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
-
-```yaml
-
-parsers:
-  - name: rasanlu
-    url: http://localhost:5000
-    project: opsdroid
-    token: 85769fjoso084jd
-    min-score: 0.8
-```
-
 ## Message object additional parameters
 
 ### `message.rasanlu`

docs/matchers/recast.ai.md

@@ -1,5 +1,22 @@
 # Recast.AI Matcher
 
+## Configuring opsdroid
+
+In order to enable Recast.AI skills, you must specify an `access-token` for your bot in the parsers section of the opsdroid configuration file. 
+You can find this `access-token` in the settings of your bot under the name: `'Request access token'`. 
+
+You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
+
+```yaml
+
+parsers:
+  - name: recastai
+    access-token: 85769fjoso084jd
+    min-score: 0.8
+```
+
+##
+
 [Recast.AI](https://recast.ai/) is an NLP API for matching strings to [intents](https://recast.ai/docs/intent). Intents are created on the Recast.AI website.
 
 ## [Example 1](#example1)
@@ -40,21 +57,6 @@ If you want to use Recast.AI in a different language other than English, all you
 
 _Note: "If you do not have any expressions in this language, we will use your default bot language for processing." - [Recast.AI Language page](https://recast.ai/docs/language)_
 
-## Configuring opsdroid
-
-In order to enable Recast.AI skills, you must specify an `access-token` for your bot in the parsers section of the opsdroid configuration file. 
-You can find this `access-token` in the settings of your bot under the name: `'Request access token'`. 
-
-You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
-
-```yaml
-
-parsers:
-  - name: recastai
-    access-token: 85769fjoso084jd
-    min-score: 0.8
-```
-
 ## Message object additional parameters
 
 ### `message.recastai`

docs/matchers/regex.md

@@ -1,5 +1,19 @@
 # Regular Expression Matcher
 
+## Configuring opsdroid
+
+In order to enable regex skills you must set the `enabled` parameter to true in the parsers section of the opsdroid configuration file.
+
+If a skill is configured with both the regex and some other NLU matcher then users who don't use NLU will get a simple regex match. However users with some other NLU configured will get matches on more flexible messages, but will not see duplicate responses where the regex also matched.
+
+```yaml
+parsers:
+  - name: regex
+    enabled: true
+```
+
+##
+
 This is the simplest matcher available in opsdroid. It matches the message from the user against a regular expression. If the regex matches the function is called.
 
 _note: The use of position anchors(`^` or `$`) are encouraged when using regex to match a function. This should prevent opsdroid to be triggered with every use of the matched regular expression_

docs/matchers/webhook.md

@@ -1,5 +1,16 @@
 # Webhook Matcher
 
+**Config**
+
+```yaml
+skills:
+  - name: "exampleskill"
+```
+
+The above skill would be called if you send a POST to `http://localhost:8080/skill/exampleskill/examplewebhook`. As the skill is being triggered by a webhook the `message` argument being passed in will be set to the [aiohttp Request](http://aiohttp.readthedocs.io/en/stable/web_reference.html#aiohttp.web.BaseRequest), this means you need to create an empty message to respond to. You will also need to know which connector, and possibly which room, to send the message back to. For this you can use the `opsdroid.default_connector` and `opsdroid.default_connector.default_room` properties to get some sensible defaults.
+
+##
+
 Similar to the crontab matcher this matcher doesn't take a message as an input, it takes a webhook instead. It allows you to trigger the skill by calling a specific URL endpoint.
 
 ## Example
@@ -23,11 +34,3 @@ async def mycrontabskill(opsdroid, config, message):
     await message.respond('Hey')
 ```
 
-**Config**
-
-```yaml
-skills:
-  - name: "exampleskill"
-```
-
-The above skill would be called if you send a POST to `http://localhost:8080/skill/exampleskill/examplewebhook`. As the skill is being triggered by a webhook the `message` argument being passed in will be set to the [aiohttp Request](http://aiohttp.readthedocs.io/en/stable/web_reference.html#aiohttp.web.BaseRequest), this means you need to create an empty message to respond to. You will also need to know which connector, and possibly which room, to send the message back to. For this you can use the `opsdroid.default_connector` and `opsdroid.default_connector.default_room` properties to get some sensible defaults.

docs/matchers/wit.ai.md

@@ -1,5 +1,22 @@
 # wit.ai Matcher
 
+## Configuring opsdroid
+
+In order to enable wit.ai skills, you must specify an `access-token` for your bot in the parsers section of the opsdroid configuration file. 
+You can find this `access-token` in the settings of your App under the name: `'Server Access Token: '`. 
+
+You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
+
+```yaml
+
+parsers:
+  - name: witai
+    access-token: XJF475SKGITJ98KHFO
+    min-score: 0.6
+```
+
+##
+
 [wit.ai](https://wit.ai) is an NLP API for matching strings to [intents](https://wit.ai/docs/recipes#categorize-the-user-intent). Intents are created on the wit.ai website.
 
 ## [Example 1](#example1)
@@ -34,21 +51,6 @@ You can find a quick getting started with the wit.ai guide [here](https://wit.ai
 
 If you want to use wit.ai in a different language other than English, all you need to do is change the language of your app located in the app settings.
 
-## Configuring opsdroid
-
-In order to enable wit.ai skills, you must specify an `access-token` for your bot in the parsers section of the opsdroid configuration file. 
-You can find this `access-token` in the settings of your App under the name: `'Server Access Token: '`. 
-
-You can also set a `min-score` option to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. The default for this is 0 which will match all messages.
-
-```yaml
-
-parsers:
-  - name: witai
-    access-token: XJF475SKGITJ98KHFO
-    min-score: 0.6
-```
-
 ## Message object additional parameters
 
 ### `message.witai`