Move the config option documentation to the config docs

matrix-org · May 16, 2022 · 35839a0 · 35839a0
1 parent fb04e7a
commit 35839a0
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 75 deletions.
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
@@ -1043,43 +1043,6 @@ media_store_path: "DATADIR/media_store"
 #    height: 600
 #    method: scale
 
-# Configure media retention settings. Media will be purged if it
-# has not been accessed in at least this amount of time. If the
-# media has never been accessed, the media's creation time is used
-# instead. Both thumbnails and the original media will be removed.
-#
-# Media is 'accessed' when loaded in a room in a client, or
-# otherwise downloaded by a local or remote user.
-#
-# Purging the media will be the carried out by the media worker
-# (whichever worker has the 'enable_media_repo' homeserver config
-# option enabled). This may be the main process.
-#
-media_retention:
-    # Whether media retention settings should apply. Defaults to
-    # false.
-    #
-    # Uncomment to enable media retention on this homeserver.
-    #
-    #enabled: true
-
-    # How long to keep local media since its last access. Local
-    # media that is removed will be permanently deleted.
-    #
-    # If this option is not set, local media will not have a
-    # retention policy applied.
-    #
-    #local_media_lifetime: 30d
-
-    # How long to keep downloaded remote media since its last
-    # access. Remote media will be downloaded again from the
-    # originating server on demand.
-    #
-    # If this option is not set, remote media will not have a
-    # retention policy applied.
-    #
-    remote_media_lifetime: 7d
-
 # Is the preview URL API enabled?
 #
 # 'false' by default: uncomment the following to enable it (and specify a

diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
@@ -1407,7 +1407,7 @@ federation_rr_transactions_per_room_per_second: 40
 ```
 ---
 ## Media Store ##
-Config options relating to Synapse media store.
+Config options related to Synapse's media store.
 
 ---
 Config option: `enable_media_repo` 
@@ -1511,6 +1511,37 @@ thumbnail_sizes:
     height: 600
     method: scale
 ```
+---
+Config option: `media_retention`
+
+Controls whether local media and entries in the remote media cache
+(media that is downloaded from other homeservers) should be removed
+under certain conditions, typically for the purpose of saving space.
+
+Purging media files will be the carried out by the media worker
+(that is, the worker that has the `enable_media_repo` homeserver config
+option set to 'true'). This may be the main process.
+
+The `media_retention.enabled` option globally controls whether media
+retention is enabled.
+
+The `media_retention.local_media_lifetime` and
+`media_retention.remote_media_lifetime` config options control whether
+media will be purged if it has not been accessed in a given amount of
+time. Note that media is 'accessed' when loaded in a room in a client, or
+otherwise downloaded by a local or remote user. If the media has never
+been accessed, the media's creation time is used instead. Both thumbnails
+and the original media will be removed. If either of these options are unset,
+then media of that type will not be purged.
+
+Example configuration:
+```yaml
+media_retention:
+    enabled: true
+    local_media_lifetime: 30d
+    remote_media_lifetime: 7d
+```
+---
 Config option: `url_preview_enabled`
 
 This setting determines whether the preview URL API is enabled.

diff --git a/synapse/config/repository.py b/synapse/config/repository.py
@@ -306,43 +306,6 @@ def generate_config_section(self, data_dir_path: str, **kwargs: Any) -> str:
         #thumbnail_sizes:
 %(formatted_thumbnail_sizes)s
 
-        # Configure media retention settings. Media will be purged if it
-        # has not been accessed in at least this amount of time. If the
-        # media has never been accessed, the media's creation time is used
-        # instead. Both thumbnails and the original media will be removed.
-        #
-        # Media is 'accessed' when loaded in a room in a client, or
-        # otherwise downloaded by a local or remote user.
-        #
-        # Purging the media will be the carried out by the media worker
-        # (whichever worker has the 'enable_media_repo' homeserver config
-        # option enabled). This may be the main process.
-        #
-        media_retention:
-            # Whether media retention settings should apply. Defaults to
-            # false.
-            #
-            # Uncomment to enable media retention on this homeserver.
-            #
-            #enabled: true
-
-            # How long to keep local media since its last access. Local
-            # media that is removed will be permanently deleted.
-            #
-            # If this option is not set, local media will not have a
-            # retention policy applied.
-            #
-            #local_media_lifetime: 30d
-
-            # How long to keep downloaded remote media since its last
-            # access. Remote media will be downloaded again from the
-            # originating server on demand.
-            #
-            # If this option is not set, remote media will not have a
-            # retention policy applied.
-            #
-            remote_media_lifetime: 7d
-
         # Is the preview URL API enabled?
         #
         # 'false' by default: uncomment the following to enable it (and specify a