From dffb23afc2b90e9cd2fb0c6597655fd50e733f69 Mon Sep 17 00:00:00 2001
From: Rhea Parekh <rheaparekh12@gmail.com>
Date: Wed, 30 May 2018 22:31:17 +0530
Subject: [PATCH] Matrix: update the integration documentation.

---
 templates/zerver/integrations/matrix.md | 66 ++++++++++++++-----------
 1 file changed, 37 insertions(+), 29 deletions(-)

diff --git a/templates/zerver/integrations/matrix.md b/templates/zerver/integrations/matrix.md
index a2b7e6b9fe..9d0362058c 100644
--- a/templates/zerver/integrations/matrix.md
+++ b/templates/zerver/integrations/matrix.md
@@ -30,39 +30,47 @@ virtualenv (from e.g. a new shell), you can use the `source` command.
 
 {!create-stream.md!}
 
-Next, on your Zulip settings page, create a generic bot for Matrix,
-preferably with a formal name like `matrix-bot`.
-It is important that you subscribe this bot to the stream which is going
-to act as the bridge.
-Note its username, API key and full name; you will use them in the
-next step.
+1. Next, on your Zulip settings page, create a generic bot for Matrix,
+   preferably with a formal name like `matrix-bot`.
 
-In `matrix_bridge_config.py` enter the following details under `zulip`
-keyword:
-```
-"email": "matrix-bot@chat.zulip.org",
-"api_key": "your_key",
-"site": "https://chat.zulip.org",
-"stream": "Stream which acts as the bridge",
-"topic": "Topic of the stream"
-```
+1. Subscribe this bot to the Zulip stream where you'd like the bridge
+   traffic to be sent.
 
-Now, create a user on [matrix.org](https://matrix.org/), preferably with a
-formal name like `zulip-bot`.
+1.  Edit `zulip/integrations/matrix/matrix_bridge_config.py`, providing
+    the following values for the `zulip` section (the first 3 values
+    come from a `zuliprc` file):
 
-In `matrix_bridge_config.py` enter the follow details under `matrix` keyword:
-```
-"host": "https://matrix.org",
-"username": "username of matrix.org user",
-"password": "password of matrix.org user",
-"room_id": "#room:matrix.org"
-```
+    ```
+    "zulip": {
+        "email": "matrix-bot@chat.zulip.org",
+        "api_key": "your_key",
+        "site": "https://chat.zulip.org",
+        "stream": "Stream which acts as the bridge",
+        "topic": "Topic of the stream"
+    }
+    ```
 
-If you want to change the displayed message template in Matrix or Zulip,
-change the variables `MATRIX_MESSAGE_TEMPLATE` and `ZULIP_MESSAGE_TEMPLATE`,
-with a suitable template.
+1. Now, create a user on [matrix.org](https://matrix.org/), preferably
+   with a formal name like `zulip-bot`.
 
-After the steps above have been completed, run `python matrix_bridge.py` to
-start the mirroring.
+1.  Edit `matrix_bridge_config.py` to add the Matrix-side settings:
+
+    ```
+    "matrix": {
+        "host": "https://matrix.org",
+        "username": "username of matrix.org user",
+        "password": "password of matrix.org user",
+        "room_id": "#room:matrix.org"
+    }
+    ```
+
+1. After the steps above have been completed, run `python matrix_bridge.py` to
+start mirroring content.
+
+If you want to customize the message formatting, you can do so by
+editing the variables `MATRIX_MESSAGE_TEMPLATE` and
+`ZULIP_MESSAGE_TEMPLATE` in
+`zulip/integrations/matrix/matrix_bridge.py`, with a suitable
+template.
 
 **Congratulations! You have created the bridge successfully!**