Updated example configuration and added basic configuration docs.

README.md

@@ -29,6 +29,8 @@ path. Do it like:
 opensaps -config /path/to/opensaps.yaml
 ```
 
+There is some documentation available - check out ``doc`` directory!
+
 # About hooks and parsers
 
 While configuring a webhook in your application, please, set username

doc/configuration.md

@@ -0,0 +1,73 @@
+# OpenSAPS configuration
+
+There is no hardcoded place for OpenSAPS configuration. You **should**
+provide path to configuration file via ``-config`` parameter.
+
+# Example configuration
+
+Example can be viewed in opensaps.example.yaml, which is stored in root
+directory of this repository.
+
+# Configuration values.
+
+Here we will go thru configuration values available. Nesting shows
+nesting level in configuration file.
+
+* ``slackhandler`` - namespace for configuring Slack API HTTP listener.
+
+  * ``listener`` - namespace for configuring HTTP listener itself.
+
+    * ``address`` - IP address and port we will listen on. Defaulting
+    to ``127.0.0.1:39231``.
+
+* ``webhooks`` - namespace for webhooks configuration. Here you should
+define webhook name (**should be unique!**) and some parameters.
+
+  * ``gitea_to_matrix`` - example webhook name. Should be unique and
+  can be anything you can imagine (in text, of course).
+
+  **WARNING:** multiline webhook names wasn't tested! Try to keep
+  your text in single line!
+
+    * ``slack`` - namespace for configuring Slack API parameters.
+    URL for Slack webhook looks like:
+
+    ```
+    http(s)://server.tls/services/T12345678/B87654321/24charslongstring
+    ```
+
+    Where ``12345678`` is a random 8-char string (all caps) and
+    ``24charslongstring`` is a random 24-char string.
+
+    Next variables configures these strings.
+
+      * ``random1`` - first 8-char random string (``T12345678``).
+
+      * ``random2`` - second 8-char random string (``B87654321``).
+
+      * ``longrandom`` - 24-char random string.
+
+    * ``remote`` - configures pusher this webhook should use and
+    connection name for it.
+
+      * ``pusher`` - what pusher this webhook should use.
+
+      * ``push_to`` - connection name for this pusher.
+
+* ``matrix`` - configures Matrix pusher connections available.
+
+  * ``matrix_test`` - connection name. Should be unique and
+  can be anything you can imagine (in text, of course).
+
+  **WARNING:** multiline webhook names wasn't tested! Try to keep
+  your text in single line!
+
+    * ``api_root`` - API root for Matrix connection. For example,
+    ``https://localhost:8448/_matrix/client/r0``.
+
+    * ``user`` - Matrix user.
+
+    * ``password`` - password for Matrix user.
+
+    * ``room`` - room ID to use. If Matrix user isn't in that room
+    while OpenSAPS logging in - OpenSAPS will try to join this room.

opensaps.example.yaml

@@ -1,7 +1,6 @@
 slackhandler:
   listener:
-    address: "127.0.0.1"
+    address: "127.0.0.1:39231"
-    port: 39231
 webhooks:
   gitea_to_matrix:
     slack:
@@ -9,10 +8,11 @@ webhooks:
       random2: "87654321"
       longrandom: "123456789012345678901234"
     remote:
+      pusher: "matrix"
       push_to: "matrix_test"
-      data: "room_id_from_config"
 matrix:
   matrix_test:
     api_root: "https://localhost:8448/_matrix/client/r0"
     user: ""
     password: ""
+    room: "!roomid:server.tld"