Merge pull request #56 from nzlosh/docs

readthedocs documentation

README.md

@@ -1,69 +1,12 @@
-# Errbot Backend for Mattermost
+# Mattermost backend for Errbot
 
-### REQUIREMENTS
-- Mattermost with APIv4
-- Python >= 3.4
-- websockets 3.2
-- [mattermostdriver](https://github.com/Vaelor/python-mattermost-driver) > 4.0
+This is the Mattermost backend for errbot.
 
-### INSTALLATION
+# Documentation
 
-- `git clone https://github.com/errbotio/errbot-mattermost-backend.git`
-- Create an account for the bot on the server.
-- Install the requirements.
-- Open errbot's config.py:
+Visit the [official documentation](https://err-backend-mattermost.readthedocs.io/) where you'll find information on the following topics:
+ - Installation
+ - Configuration
+ - User Guide
+ - Developer Guide
 
-```
-BACKEND = 'Mattermost'
-BOT_EXTRA_BACKEND_DIR = '/path/to/backends'
-
-BOT_ADMINS = ('@yourname') # Names need the @ in front!
-
-BOT_IDENTITY = {
-        # Required
-        'team': 'nameoftheteam',
-        'server': 'mattermost.server.com',
-        # For the login, either
-        'login': '[email protected]',
-        'password': 'botpassword',
-        # Or, if you have a personal access token
-        'token': 'YourPersonalAccessToken',
-        # Optional
-        'insecure': False, # Default = False. Set to true for self signed certificates
-        'scheme': 'https', # Default = https
-        'port': 8065, # Default = 8065
-        'timeout': 30, # Default = 30. If the webserver disconnects idle connections later/earlier change this value
-        'cards_hook': 'incomingWebhookId' # Needed for cards/attachments
-}
-```
-
-- If the bot has problems doing some actions, you should make it system admin, some actions won't work otherwise.
-
-### Cards/Attachments
-Cards are called attachments in Mattermost.
-If you want to send attachments, you need to create an incoming Webhook in Mattermost
-and add the webhook id to your errbot `config.py` in `BOT_IDENTITY`.
-This is not an ideal solution, but AFAIK Mattermost does not support sending attachments
-over the api like slack does.
-
-### APIv3
-Use the APIv3 branch for that. It is no longer supported and not guaranteed to work!
-
-**Attention**: The `BOT_IDENTITY` config options are different for V3 and V4!
-
-### KNOWN (POSSIBLE) ISSUES
-
-- Channelmentions in messages aren't accounted for (Unsure if they need to be)
-
-### FAQ
-
-##### The Bot does not answer my direct messages
-If you have multiple teams, check that you are both members of the same team!
-
-# SPECIAL THANKS
-
-**Thanks** to http://errbot.io and all the contributors to the bot.
-Most of this code was build with help from the already existing backends,
-especially:
-https://github.com/errbotio/errbot/blob/master/errbot/backends/slack.py
-(If there is an Issue with any code I reused, please give me a message!)

docs/configuration.rst

@@ -0,0 +1,36 @@
+.. _configuration:
+
+Configuration
+========================================================================
+
+To configure mattermost as errbot's backend, you must edit `config.py`, which is created as part of the errbot initialisation process or downloaded from the official errbot documentation.
+
+
+.. code-block:: python
+
+    BACKEND = 'Mattermost'
+    BOT_EXTRA_BACKEND_DIR = '/path/to/backends'
+
+    BOT_ADMINS = ('@yourname') # Names need the @ in front!
+
+    BOT_IDENTITY = {
+        # Required
+        "team": "nameoftheteam",
+        "server": "mattermost.server.com",
+        # For the login, either
+        "login": "[email protected]",
+        "password": "botpassword",
+        # Or, if you have a personal access token
+        "token": "YourPersonalAccessToken",
+        # Optional
+        "insecure": False,                  # Default = False. Set to true for self signed certificates
+        "scheme": "https",                  # Default = https
+        "port": 8065,                       # Default = 8065
+        "timeout": 30,                      # Default = 30. If the web server disconnects idle connections later/earlier change this value
+        "cards_hook": "incomingWebhookId"   # Needed for cards/attachments
+    }
+
+
+.. note:: The above configuration example only shows mattermost settings, but all errbot configuration settings.  Use the official errbot documentation to complete the above example.
+
+.. important:: Some Mattermost actions can only be performed with administrator rights.  If the bot has problems performing an action, check the bot account permissions and grant the appropriate rights.

docs/developer_guide.rst

@@ -0,0 +1,13 @@
+.. _developer_guide:
+
+Developer Guide
+========================================================================
+
+The process for contributing to the mattermost backend follows the traditional github methodology.
+
+1. Fork the github project to your github account.
+2. Clone the forked repository to your development machine.
+3. Create a branch for changes in your locally cloned repository.
+4. Develop feature/fix/change in your branch.
+5. Push work from your branch to your forked repository
+6. Open pull request from your forked repository to the official err-backend-mattermost repository.

docs/index.rst

@@ -0,0 +1,27 @@
+
+.. title:: err-backend-mattermost documentation
+
+Errbot Mattermost Backend Documentation
+========================================================================
+
+Welcome to the ``err-backend-mattermost`` documentation page.  You'll be able to find
+installation instructions, configuration information and examples of using some of the backend's features.
+
+The ``err-backend-mattermost`` backend lets you connect errbot to the `Mattermost <https://https://mattermost.com/>`_ open source collaboration platform.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation.rst
+   configuration.rst
+   user_guide.rst
+   developer_guide.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,38 @@
+.. _installation:
+
+Installation
+========================================================================
+
+.. contents:: :local:
+
+Requirements
+------------------------------------------------------------------------
+
+ - Mattermost with APIv4
+ - Python >= 3.7
+ - websockets 3.2
+ - `mattermostdriver <https://github.com/Vaelor/python-mattermost-driver>`_ > 4.0
+
+
+Python Virtual Environment
+------------------------------------------------------------------------
+
+These instructions assume you have a mattermost instance up and running with a bot account configured.  For information on how to setup the bot account see https://developers.mattermost.com/integrate/reference/bot-accounts/
+
+    1. Create a virtual environment for errbot.
+    ::
+
+        python3 -m venv <path_to_virtualenv>
+        source <path_to_virtualenv>/bin/activate
+
+    2. Install errbot and mattermost backend.
+    ::
+
+        pip install errbot mattermost
+
+    3. Initialise errbot and configure mattermost.
+    ::
+
+        errbot --init
+
+    4. See the :ref:`configuration` section for configuration details.

docs/user_guide.rst

@@ -0,0 +1,45 @@
+.. _user_guide:
+
+User Guide
+========================================================================
+
+.. contents:: :local:
+
+Cards/Attachments
+------------------------------------------------------------------------
+
+Cards are called _attachments_ in Mattermost.
+
+If you want to send attachments, you need to create an incoming Webhook in Mattermost
+and add the webhook id to your errbot `config.py` in `BOT_IDENTITY`.
+
+This is not an ideal solution, but AFAIK Mattermost does not support sending attachments
+over the api like slack does.
+
+
+APIv3
+------------------------------------------------------------------------
+Mattermost has deprecated the v3 API.  If you are still running APIv3, you're strongly encourage to upgrade.
+Despite this, there is an APIv3 branch in the github repository that you can try but keep in mind that it is no longer supported and not guaranteed to work!  
+
+.. important:: The `BOT_IDENTITY` config options are different for APIv3 and APIv4!
+
+
+Known (possible) Issues
+------------------------------------------------------------------------
+
+- Channel mentions in messages aren't accounted for and it is unclear if they need to be.  If you think they should be or you've encountered an error, please open an issue against the err-backend-mattermost github repository.
+
+
+F.A.Q.
+------------------------------------------------------------------------
+
+The Bot does not answer my direct messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you have multiple teams, check that you are both members of the same team!
+
+
+Special thanks
+------------------------------------------------------------------------
+
+**Thanks** to http://errbot.io/ the contributors.  The mattermost backend has been derived from the backends from there.