Merge branch 'develop' of github.com:matrix-org/synapse into events_refactor

Conflicts:
	setup.py

2 files changed, 28 insertions, 3 deletions

diff --git a/docs/code_style.rst b/docs/code_style.rst
index 6e53f3eb09..dc40a7ab7b 100644
--- a/docs/code_style.rst
+++ b/docs/code_style.rst
@@ -22,17 +22,17 @@ Basically, PEP8
   depending on the size and shape of the arguments and what makes more sense to
   the author. In other words, both this::
 
-    print("I am a fish %s", "moo")
+    print("I am a fish %s" % "moo")
 
   and this::
 
-    print("I am a fish %s",
+    print("I am a fish %s" %
           "moo")
 
   and this::
 
     print(
-        "I am a fish %s",
+        "I am a fish %s" %
         "moo"
     )
 
diff --git a/docs/media_repository.rst b/docs/media_repository.rst
new file mode 100644
index 0000000000..e4a6974041
--- /dev/null
+++ b/docs/media_repository.rst
@@ -0,0 +1,25 @@
+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/..."``