Merge branch 'docs-config' into 'master'

[Docs] Add setup instructions

Closes #17

See merge request !11

docs/admin/00_index.rst

+Setting up Matrix synchronization
+=================================
+
+.. toctree::
+   :glob:
+
+   *

docs/admin/01_intro.rst

+Matrix and Element
+==================
+
+`Matrix`_ is "an open network for secure, decentralized communication".
+Being an open protocol, it allows independent implementations of servers
+and clients to communicate with each other.
+Users create their account on a server they choose and are then able to
+chat with everyone in the network, just like the e-mail system works.
+
+The popular reference client `Element`_ with its team communication friendly
+user interface is a good choice for schools.
+It is available as a mobile app for Android and iOS, and as a web client,
+that can be used in a web browser.
+
+.. _Matrix: https://www.matrix.org/
+.. _Element: https://https://element.io/

docs/admin/02_concepts.rst

+Concepts of rooms and spaces
+============================
+
+In Matrix, every chat is organized as a room, where people can join
+to send and receive messages.
+Schools can map their real structure to Matrix rooms to provide each
+group or course a place to communicate.
+
+A Space is an organizational layer, that contains multiple rooms and
+can even contain other spaces. This is useful for representing child
+and parent group relationships.
+
+When the Spaces feature is enabled, AlekSIS will create a space for
+e.g. class 5a that contains the rooms 5a English, 5a Maths etc..

docs/admin/10_configuration.rst

+Configuring Matrix connection
+=============================
+
+To connect AlekSIS to Matrix, an Account on a Matrix homeserver is required.
+Most homeservers of schools will not have open registration, so the process of
+creating an account depends on the school's setup.
+
+Extracting the access token from Element Web
+--------------------------------------------
+
+Log in to the Matrix account intended to use for AlekSIS synchronization and
+open the settings via ``Profile picture → All Settings``.
+Go to the tab ``Help & About`` and expand ``Access Token`` in the ``Advanced`` section.
+The access token will be displayed and can be copied.
+
+After that, do not log out of Element, because that would invalidate the access token.
+You might want to use a private tab in your browser or clear session data afterwards.
+
+Creating a new user via open registration
+-----------------------------------------
+
+To create rooms and spaces and manage their participants,
+AlekSIS needs to have a Matrix user that can be created using ``curl``::
+
+  curl -XPOST -d '{"username":"aleksis", "password":"randomlygenerated", "auth": {"type":"m.login.dummy"}}' "https://example.org/_matrix/client/r0/register"
+
+When the registration succeeds, a Matrix ID (user_id) and an access token will be returned::
+
+  {
+    "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.AqdSzFmFYrLrTmteXc",
+    "home_server": "example.org",
+    "user_id": "@aleksis:example.org"
+  }
+
+Connecting AlekSIS to the Matrix user
+-------------------------------------
+
+In AlekSIS, go to ``Admin → Configuration → Matrix``.
+Fill in the URL of the Matrix homeserver and the previously extracted access token.
+
+Setting up auto-generated Matrix IDs for AlekSIS users
+------------------------------------------------------
+
+For dedicated Matrix homeservers that use AlekSIS as a SSO provider
+or use the same SSO provider or user database, e.g. LDAP, AlekSIS can
+automatically generate Matrix IDs for its users based on the username.
+
+To enable this feature, provide a value for ``Name of Matrix homeserver user for auto-generating Matrix IDs``.
+
+Configuring synchronization
+---------------------------
+
+AlekSIS' Matrix synchronization creates Matrix rooms for every group and invites the respective users.
+Details of the synchronization can be customized with the remaining config options:
+
+* **Disambiguate room aliases**: Room aliases are built from the group's short name or name. To avoid name collisions, a suffix will be added when this option is enabled.
+* **Use Spaces**: Matrix supports grouping of rooms in so-called spaces. In a school context that can be used to create a space for each class containg rooms for all their subjects, i.e. child groups in AlekSIS.
+* **Power level for owners**: Specifies the Matrix room power level for group owners.
+* **Power level for members**: Specifies the Matrix room power level for group members.
+* **Reduce existing power levels**: For existing Matrix rooms that are going to be managed by AlekSIS, power levels can be overwritten by AlekSIS to match the previously defined power levels.

docs/admin/20_syncing.rst

+Synchronizing with Matrix
+=========================
+
+To initially start the synchronization of groups in AlekSIS to rooms,
+and optionally spaces, to Matrix, go to ``Matrix → Groups and Rooms``.
+
+Select the groups to be synchronized and click ``Execute``.
+This process can take some time.
+All group members that have a Matrix profile in AlekSIS, that may be automatically
+created when a ``Name of Matrix homeserver user for auto-generating Matrix IDs`` is set,
+get invited to the respective rooms.
+
+.. image:: ../_static/sync.png
+   :alt: Synchronizing AlekSIS with Matrix
+
+After this initial synchronization, every change in a ``Group``, ``Matrix room`` or
+``Matrix profile`` will be refleceted in Matrix.

docs/index.rst

@@ -10,6 +10,8 @@ Welcome to AlekSIS-App-Matrix' documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   admin/00_index
+
 Indices and tables
 ==================