(matrix-org#5849) Convert rst to markdown

First pass at converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change. Submitted more for feedback before continuing further. Signed-off-by: David Stipp <dstipp@coolhack.net>
dstipp · Aug 25, 2019 · 099cbdc · 099cbdc
1 parent 8767b63
commit 099cbdc
Show file tree

Hide file tree

Showing 9 changed files with 190 additions and 200 deletions.
diff --git a/docs/CAPTCHA_SETUP.rst → docs/CAPTCHA_SETUP.md b/docs/CAPTCHA_SETUP.rst → docs/CAPTCHA_SETUP.md
@@ -2,29 +2,32 @@ Captcha can be enabled for this home server. This file explains how to do that.
 The captcha mechanism used is Google's ReCaptcha. This requires API keys from Google.
 
 Getting keys
-------------
+============
+
 Requires a public/private key pair from:
 
-https://developers.google.com/recaptcha/
+<https://developers.google.com/recaptcha/>
 
 Must be a reCAPTCHA v2 key using the "I'm not a robot" Checkbox option
 
 Setting ReCaptcha Keys
-----------------------
+======================
+
 The keys are a config option on the home server config. If they are not
-visible, you can generate them via --generate-config. Set the following value::
+visible, you can generate them via `--generate-config`. Set the following value:
 
-  recaptcha_public_key: YOUR_PUBLIC_KEY
-  recaptcha_private_key: YOUR_PRIVATE_KEY
+    recaptcha_public_key: YOUR_PUBLIC_KEY
+    recaptcha_private_key: YOUR_PRIVATE_KEY
 
-In addition, you MUST enable captchas via::
+In addition, you MUST enable captchas via:
 
-  enable_registration_captcha: true
+    enable_registration_captcha: true
 
 Configuring IP used for auth
-----------------------------
+============================
+
 The ReCaptcha API requires that the IP address of the user who solved the
 captcha is sent. If the client is connecting through a proxy or load balancer,
-it may be required to use the X-Forwarded-For (XFF) header instead of the origin
-IP address. This can be configured using the x_forwarded directive in the
+it may be required to use the `X-Forwarded-For` (XFF) header instead of the origin
+IP address. This can be configured using the `x_forwarded` directive in the
 listeners section of the homeserver.yaml configuration file.
diff --git a/docs/README.rst → docs/README.md b/docs/README.rst → docs/README.md
diff --git a/docs/application_services.md b/docs/application_services.md
@@ -0,0 +1,32 @@
+Registering an Application Service
+==================================
+
+The registration of new application services depends on the homeserver used. 
+In synapse, you need to create a new configuration file for your AS and add it
+to the list specified under the ``app_service_config_files`` config
+option in your synapse config.
+
+For example:
+
+``` {.sourceCode .yaml}
+app_service_config_files:
+- /home/matrix/.synapse/<your-AS>.yaml
+```
+
+The format of the AS configuration file is as follows:
+
+``` {.sourceCode .yaml}
+url: <base url of AS>
+as_token: <token AS will add to requests to HS>
+hs_token: <token HS will add to requests to AS>
+sender_localpart: <localpart of AS user>
+namespaces:
+  users:  # List of users we're interested in
+    - exclusive: <bool>
+      regex: <regex>
+    - ...
+  aliases: []  # List of aliases we're interested in
+  rooms: [] # List of room ids we're interested in
+```
+
+See the [spec](https://matrix.org/docs/spec/application_service/unstable.html) for further details on how application services work.
diff --git a/docs/application_services.rst b/docs/application_services.rst
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,67 @@
+Synapse Architecture
+====================
+
+As of the end of Oct 2014, Synapse's overall architecture looks like:
+
+        synapse
+        .-----------------------------------------------------.
+        |                          Notifier                   |
+        |                            ^  |                     |
+        |                            |  |                     |
+        |                  .------------|------.              |
+        |                  | handlers/  |      |              |
+        |                  |            v      |              |
+        |                  | Event*Handler <--------> rest/* <=> Client
+        |                  | Rooms*Handler     |              |
+    HS <=> federation/* <==> FederationHandler |              |
+        |      |           | PresenceHandler   |              |
+        |      |           | TypingHandler     |              |
+        |      |           '-------------------'              |
+        |      |                 |     |                      |
+        |      |              state/*  |                      |
+        |      |                 |     |                      |
+        |      |                 v     v                      |
+        |      `--------------> storage/*                     |
+        |                          |                          |
+        '--------------------------|--------------------------'
+                                   v
+                                .----.
+                                | DB |
+                                '----'
+
+-   Handlers: business logic of synapse itself. Follows a set contract of BaseHandler:
+    -   BaseHandler gives us onNewRoomEvent which: (TODO: flesh this out and make it less cryptic):
+        -   handle_state(event)
+        -   auth(event)
+        -   persist_event(event)
+        -   notify notifier or federation(event)
+    -   PresenceHandler: use distributor to get EDUs out of Federation.
+        Very lightweight logic built on the distributor
+    -   TypingHandler: use distributor to get EDUs out of Federation.
+        Very lightweight logic built on the distributor
+    -   EventsHandler: handles the events stream\...
+    -   FederationHandler: - gets PDU from Federation Layer; turns into
+        an event; follows basehandler functionality.
+    -   RoomsHandler: does all the room logic, including members - lots
+        of classes in RoomsHandler.
+    -   ProfileHandler: talks to the storage to store/retrieve profile
+        info.
+-   EventFactory: generates events of particular event types.
+-   Notifier: Backs the events handler
+-   REST: Interfaces handlers and events to the outside world via
+    HTTP/JSON. Converts events back and forth from JSON.
+-   Federation: holds the HTTP client & server to talk to other servers.
+    Does replication to make sure there\'s nothing missing in the graph.
+    Handles reliability. Handles txns.
+-   Distributor: generic event bus. used for presence & typing only
+    currently. Notifier could be implemented using Distributor - so far
+    we are only using for things which actually /require/ dynamic
+    pluggability however as it can obfuscate the actual flow of control.
+-   Auth: helper singleton to say whether a given event is allowed to do
+    a given thing (TODO: put this on the diagram)
+-   State: helper singleton: does state conflict resolution. You give it
+    an event and it tells you if it actually updates the state or not,
+    and annotates the event up properly and handles merge conflict
+    resolution.
+-   Storage: abstracts the storage engine.
+
diff --git a/docs/architecture.rst b/docs/architecture.rst
diff --git a/docs/media_repository.md b/docs/media_repository.md
@@ -0,0 +1,32 @@
+Media Repository 
+================
+
+*Synapse implementation-specific details for the media repository*
+
+The media repository is where attachments and avatar photos are stored.
+It stores attachment content and thumbnails for media uploaded by local users.
+It caches attachment content and thumbnails for media uploaded by remote users.
+
+Storage
+-------
+
+Each item of media is assigned a `media_id` when it is uploaded.
+The `media_id` is a randomly chosen, URL safe 24 character string.
+
+Metadata such as the MIME type, upload time and length are stored in the
+sqlite3 database indexed by `media_id`.
+
+Content is stored on the filesystem under a `"local_content"` directory.
+
+Thumbnails are stored under a `"local_thumbnails"` directory.
+
+The item with `media_id` `"aabbccccccccdddddddddddd"` is stored under
+`"local_content/aa/bb/ccccccccdddddddddddd"`. Its thumbnail with width
+`128` and height `96` and type `"image/jpeg"` is stored under
+`"local_thumbnails/aa/bb/ccccccccdddddddddddd/128-96-image-jpeg"`
+
+Remote content is cached under `"remote_content"` directory. Each item of
+remote content is assigned a local "`filesystem_id`" to ensure that the
+directory structure `"remote_content/server_name/aa/bb/ccccccccdddddddddddd"`
+is appropriate. Thumbnails for remote content are stored under
+`"remote_thumbnails/server_name/..."`
diff --git a/docs/media_repository.rst b/docs/media_repository.rst