Skip to content

Commit 446538b

Browse files
nzloshnzlosh
authored
Merge pull request #56 from nzlosh/docs
readthedocs documentation
2 parents 0a0425c + d3f7758 commit 446538b

File tree

6 files changed

+167
-65
lines changed

6 files changed

+167
-65
lines changed

‎README.md‎

Lines changed: 8 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,12 @@
1-
# Errbot Backend for Mattermost
1+
# Mattermost backend for Errbot
22

3-
### REQUIREMENTS
4-
- Mattermost with APIv4
5-
- Python >= 3.4
6-
- websockets 3.2
7-
- [mattermostdriver](https://github.com/Vaelor/python-mattermost-driver) > 4.0
3+
This is the Mattermost backend for errbot.
84

9-
### INSTALLATION
5+
# Documentation
106

11-
- `git clone https://github.com/errbotio/errbot-mattermost-backend.git`
12-
- Create an account for the bot on the server.
13-
- Install the requirements.
14-
- Open errbot's config.py:
7+
Visit the [official documentation](https://err-backend-mattermost.readthedocs.io/) where you'll find information on the following topics:
8+
- Installation
9+
- Configuration
10+
- User Guide
11+
- Developer Guide
1512

16-
```
17-
BACKEND = 'Mattermost'
18-
BOT_EXTRA_BACKEND_DIR = '/path/to/backends'
19-
20-
BOT_ADMINS = ('@yourname') # Names need the @ in front!
21-
22-
BOT_IDENTITY = {
23-
# Required
24-
'team': 'nameoftheteam',
25-
'server': 'mattermost.server.com',
26-
# For the login, either
27-
'login': '[email protected]',
28-
'password': 'botpassword',
29-
# Or, if you have a personal access token
30-
'token': 'YourPersonalAccessToken',
31-
# Optional
32-
'insecure': False, # Default = False. Set to true for self signed certificates
33-
'scheme': 'https', # Default = https
34-
'port': 8065, # Default = 8065
35-
'timeout': 30, # Default = 30. If the webserver disconnects idle connections later/earlier change this value
36-
'cards_hook': 'incomingWebhookId' # Needed for cards/attachments
37-
}
38-
```
39-
40-
- If the bot has problems doing some actions, you should make it system admin, some actions won't work otherwise.
41-
42-
### Cards/Attachments
43-
Cards are called attachments in Mattermost.
44-
If you want to send attachments, you need to create an incoming Webhook in Mattermost
45-
and add the webhook id to your errbot `config.py` in `BOT_IDENTITY`.
46-
This is not an ideal solution, but AFAIK Mattermost does not support sending attachments
47-
over the api like slack does.
48-
49-
### APIv3
50-
Use the APIv3 branch for that. It is no longer supported and not guaranteed to work!
51-
52-
**Attention**: The `BOT_IDENTITY` config options are different for V3 and V4!
53-
54-
### KNOWN (POSSIBLE) ISSUES
55-
56-
- Channelmentions in messages aren't accounted for (Unsure if they need to be)
57-
58-
### FAQ
59-
60-
##### The Bot does not answer my direct messages
61-
If you have multiple teams, check that you are both members of the same team!
62-
63-
# SPECIAL THANKS
64-
65-
**Thanks** to http://errbot.io and all the contributors to the bot.
66-
Most of this code was build with help from the already existing backends,
67-
especially:
68-
https://github.com/errbotio/errbot/blob/master/errbot/backends/slack.py
69-
(If there is an Issue with any code I reused, please give me a message!)

‎docs/configuration.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. _configuration:
2+
3+
Configuration
4+
========================================================================
5+
6+
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.
7+
8+
9+
.. code-block:: python
10+
11+
BACKEND = 'Mattermost'
12+
BOT_EXTRA_BACKEND_DIR = '/path/to/backends'
13+
14+
BOT_ADMINS = ('@yourname') # Names need the @ in front!
15+
16+
BOT_IDENTITY = {
17+
# Required
18+
"team": "nameoftheteam",
19+
"server": "mattermost.server.com",
20+
# For the login, either
21+
"login": "[email protected]",
22+
"password": "botpassword",
23+
# Or, if you have a personal access token
24+
"token": "YourPersonalAccessToken",
25+
# Optional
26+
"insecure": False, # Default = False. Set to true for self signed certificates
27+
"scheme": "https", # Default = https
28+
"port": 8065, # Default = 8065
29+
"timeout": 30, # Default = 30. If the web server disconnects idle connections later/earlier change this value
30+
"cards_hook": "incomingWebhookId" # Needed for cards/attachments
31+
}
32+
33+
34+
.. note:: The above configuration example only shows mattermost settings, but all errbot configuration settings. Use the official errbot documentation to complete the above example.
35+
36+
.. 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‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. _developer_guide:
2+
3+
Developer Guide
4+
========================================================================
5+
6+
The process for contributing to the mattermost backend follows the traditional github methodology.
7+
8+
1. Fork the github project to your github account.
9+
2. Clone the forked repository to your development machine.
10+
3. Create a branch for changes in your locally cloned repository.
11+
4. Develop feature/fix/change in your branch.
12+
5. Push work from your branch to your forked repository
13+
6. Open pull request from your forked repository to the official err-backend-mattermost repository.

‎docs/index.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
2+
.. title:: err-backend-mattermost documentation
3+
4+
Errbot Mattermost Backend Documentation
5+
========================================================================
6+
7+
Welcome to the ``err-backend-mattermost`` documentation page. You'll be able to find
8+
installation instructions, configuration information and examples of using some of the backend's features.
9+
10+
The ``err-backend-mattermost`` backend lets you connect errbot to the `Mattermost <https://https://mattermost.com/>`_ open source collaboration platform.
11+
12+
.. toctree::
13+
:maxdepth: 2
14+
:caption: Contents:
15+
16+
installation.rst
17+
configuration.rst
18+
user_guide.rst
19+
developer_guide.rst
20+
21+
22+
Indices and tables
23+
==================
24+
25+
* :ref:`genindex`
26+
* :ref:`modindex`
27+
* :ref:`search`

‎docs/installation.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. _installation:
2+
3+
Installation
4+
========================================================================
5+
6+
.. contents:: :local:
7+
8+
Requirements
9+
------------------------------------------------------------------------
10+
11+
- Mattermost with APIv4
12+
- Python >= 3.7
13+
- websockets 3.2
14+
- `mattermostdriver <https://github.com/Vaelor/python-mattermost-driver>`_ > 4.0
15+
16+
17+
Python Virtual Environment
18+
------------------------------------------------------------------------
19+
20+
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/
21+
22+
1. Create a virtual environment for errbot.
23+
::
24+
25+
python3 -m venv <path_to_virtualenv>
26+
source <path_to_virtualenv>/bin/activate
27+
28+
2. Install errbot and mattermost backend.
29+
::
30+
31+
pip install errbot mattermost
32+
33+
3. Initialise errbot and configure mattermost.
34+
::
35+
36+
errbot --init
37+
38+
4. See the :ref:`configuration` section for configuration details.

‎docs/user_guide.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. _user_guide:
2+
3+
User Guide
4+
========================================================================
5+
6+
.. contents:: :local:
7+
8+
Cards/Attachments
9+
------------------------------------------------------------------------
10+
11+
Cards are called _attachments_ in Mattermost.
12+
13+
If you want to send attachments, you need to create an incoming Webhook in Mattermost
14+
and add the webhook id to your errbot `config.py` in `BOT_IDENTITY`.
15+
16+
This is not an ideal solution, but AFAIK Mattermost does not support sending attachments
17+
over the api like slack does.
18+
19+
20+
APIv3
21+
------------------------------------------------------------------------
22+
Mattermost has deprecated the v3 API. If you are still running APIv3, you're strongly encourage to upgrade.
23+
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!
24+
25+
.. important:: The `BOT_IDENTITY` config options are different for APIv3 and APIv4!
26+
27+
28+
Known (possible) Issues
29+
------------------------------------------------------------------------
30+
31+
- 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.
32+
33+
34+
F.A.Q.
35+
------------------------------------------------------------------------
36+
37+
The Bot does not answer my direct messages
38+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39+
If you have multiple teams, check that you are both members of the same team!
40+
41+
42+
Special thanks
43+
------------------------------------------------------------------------
44+
45+
**Thanks** to http://errbot.io/ the contributors. The mattermost backend has been derived from the backends from there.

0 commit comments

Comments
 (0)