Cleanup references to sample config in the docs and redirect users to configuration manual (#13077)

changelog.d/13077.doc

@@ -0,0 +1,3 @@
+Clean up references to sample configuration and redirect users to the configuration manual instead.
+
+

docs/admin_api/user_admin_api.md

@@ -124,9 +124,8 @@ Body parameters:
   - `address` - string. Value of third-party ID.
   belonging to a user.
 - `external_ids` - array, optional. Allow setting the identifier of the external identity
-  provider for SSO (Single sign-on). Details in
+  provider for SSO (Single sign-on). Details in the configuration manual under the
-  [Sample Configuration File](../usage/configuration/homeserver_sample_config.html)
+  sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
-  section `sso` and `oidc_providers`.
   - `auth_provider` - string. ID of the external identity provider. Value of `idp_id`
     in the homeserver configuration. Note that no error is raised if the provided
     value is not in the homeserver configuration.

docs/code_style.md

@@ -70,82 +70,61 @@ on save as they take a while and can be very resource intensive.
     -   Avoid wildcard imports (`from synapse.types import *`) and
         relative imports (`from .types import UserID`).
 
-## Configuration file format
+## Configuration code and documentation format
 
-The [sample configuration file](./sample_config.yaml) acts as a
+When adding a configuration option to the code, if several settings are grouped into a single dict, ensure that your code
+correctly handles the top-level option being set to `None` (as it will be if no sub-options are enabled).
+
+The [configuration manual](usage/configuration/config_documentation.md) acts as a
 reference to Synapse's configuration options for server administrators.
 Remember that many readers will be unfamiliar with YAML and server
-administration in general, so that it is important that the file be as
+administration in general, so it is important that when you add
-easy to understand as possible, which includes following a consistent
+a configuration option the documentation be as easy to understand as possible, which 
-format.
+includes following a consistent format.
 
 Some guidelines follow:
 
--   Sections should be separated with a heading consisting of a single
+- Each option should be listed in the config manual with the following format:
-    line prefixed and suffixed with `##`. There should be **two** blank
-    lines before the section header, and **one** after.
--   Each option should be listed in the file with the following format:
-    -   A comment describing the setting. Each line of this comment
-        should be prefixed with a hash (`#`) and a space.
       
-        The comment should describe the default behaviour (ie, what
+    - The name of the option, prefixed by `###`. 
+
+    - A comment which describes the default behaviour (i.e. what
         happens if the setting is omitted), as well as what the effect
         will be if the setting is changed.
-
+    - An example setting, using backticks to define the code block
-        Often, the comment end with something like "uncomment the
-        following to <do action>".
-
-    -   A line consisting of only `#`.
-    -   A commented-out example setting, prefixed with only `#`.
 
         For boolean (on/off) options, convention is that this example
-        should be the *opposite* to the default (so the comment will end
+        should be the *opposite* to the default. For other options, the example should give
-        with "Uncomment the following to enable [or disable]
+        some non-default value which is likely to be useful to the reader.
-        <feature>." For other options, the example should give some
-        non-default value which is likely to be useful to the reader.
 
--   There should be a blank line between each option.
+- There should be a horizontal rule between each option, which can be achieved by adding `---` before and
--   Where several settings are grouped into a single dict, *avoid* the
+  after the option.
-    convention where the whole block is commented out, resulting in
-    comment lines starting `# #`, as this is hard to read and confusing
-    to edit. Instead, leave the top-level config option uncommented, and
-    follow the conventions above for sub-options. Ensure that your code
-    correctly handles the top-level option being set to `None` (as it
-    will be if no sub-options are enabled).
--   Lines should be wrapped at 80 characters.
--   Use two-space indents.
 - `true` and `false` are spelt thus (as opposed to `True`, etc.)
--   Use single quotes (`'`) rather than double-quotes (`"`) or backticks
-    (`` ` ``) to refer to configuration options.
 
 Example:
 
+---
+### `modules`
+
+Use the `module` sub-option to add a module under `modules` to extend functionality. 
+The `module` setting then has a sub-option, `config`, which can be used to define some configuration
+for the `module`.
+
+Defaults to none.
+
+Example configuration:
 ```yaml
-## Frobnication ##
+modules:
-
+  - module: my_super_module.MySuperClass
-# The frobnicator will ensure that all requests are fully frobnicated.
+    config:
-# To enable it, uncomment the following.
+      do_thing: true
-#
+  - module: my_other_super_module.SomeClass
-#frobnicator_enabled: true
+    config: {}
-
-# By default, the frobnicator will frobnicate with the default frobber.
-# The following will make it use an alternative frobber.
-#
-#frobincator_frobber: special_frobber
-
-# Settings for the frobber
-#
-frobber:
-  # frobbing speed. Defaults to 1.
-  #
-  #speed: 10
-
-  # frobbing distance. Defaults to 1000.
-  #
-  #distance: 100
 ```
+---
 
 Note that the sample configuration is generated from the synapse code
 and is maintained by a script, `scripts-dev/generate_sample_config.sh`.
 Making sure that the output from this script matches the desired format
 is left as an exercise for the reader!
+

docs/jwt.md

@@ -49,9 +49,8 @@ as follows:
 * For other installation mechanisms, see the documentation provided by the
   maintainer.
 
-To enable the JSON web token integration, you should then add a `jwt_config` section
+To enable the JSON web token integration, you should then add a `jwt_config` option
-to your configuration file (or uncomment the `enabled: true` line in the
+to your configuration file. See the [configuration manual](usage/configuration/config_documentation.md#jwt_config) for some
-existing section). See [sample_config.yaml](./sample_config.yaml) for some
 sample settings.
 
 ## How to test JWT as a developer

docs/manhole.md

@@ -13,8 +13,10 @@ environments where untrusted users have shell access.
 
 ## Configuring the manhole
 
-To enable it, first uncomment the `manhole` listener configuration in
+To enable it, first add the `manhole` listener configuration in your
-`homeserver.yaml`. The configuration is slightly different if you're using docker.
+`homeserver.yaml`. You can find information on how to do that 
+in the [configuration manual](usage/configuration/config_documentation.md#manhole_settings).
+The configuration is slightly different if you're using docker.
 
 #### Docker config
 

docs/message_retention_policies.md

@@ -49,9 +49,9 @@ clients.
 
 ## Server configuration
 
-Support for this feature can be enabled and configured in the
+Support for this feature can be enabled and configured by adding a the
-`retention` section of the Synapse configuration file (see the
+`retention` in the Synapse configuration file (see
-[sample file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518)).
+[configuration manual](usage/configuration/config_documentation.md#retention)).
 
 To enable support for message retention policies, set the setting
 `enabled` in this section to `true`.
@@ -65,8 +65,8 @@ message retention policy configured in its state. This allows server
 admins to ensure that messages are never kept indefinitely in a server's
 database. 
 
-A default policy can be defined as such, in the `retention` section of
+A default policy can be defined as such, by adding the `retention` option in
-the configuration file:
+the configuration file and adding these sub-options:
 
 ```yaml
 default_policy:
@@ -86,8 +86,8 @@ Purge jobs are the jobs that Synapse runs in the background to purge
 expired events from the database. They are only run if support for
 message retention policies is enabled in the server's configuration. If
 no configuration for purge jobs is configured by the server admin,
-Synapse will use a default configuration, which is described in the
+Synapse will use a default configuration, which is described here in the
-[sample configuration file](https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518).
+[configuration manual](usage/configuration/config_documentation.md#retention).
 
 Some server admins might want a finer control on when events are removed
 depending on an event's room's policy. This can be done by setting the
@@ -137,8 +137,8 @@ the server's database.
 ### Lifetime limits
 
 Server admins can set limits on the values of `max_lifetime` to use when
-purging old events in a room. These limits can be defined as such in the
+purging old events in a room. These limits can be defined under the
-`retention` section of the configuration file:
+`retention` option in the configuration file:
 
 ```yaml
 allowed_lifetime_min: 1d

docs/openid.md

@@ -45,8 +45,8 @@ as follows:
    maintainer.
 
 To enable the OpenID integration, you should then add a section to the `oidc_providers`
-setting in your configuration file (or uncomment one of the existing examples).
+setting in your configuration file.
-See [sample_config.yaml](./sample_config.yaml) for some sample settings, as well as
+See the [configuration manual](usage/configuration/config_documentation.md#oidc_providers) for some sample settings, as well as
 the text below for example configurations for specific providers.
 
 ## Sample configs

docs/setup/forward_proxy.md

@@ -66,8 +66,8 @@ in Synapse can be deactivated.
 
 **NOTE**: This has an impact on security and is for testing purposes only!
 
-To deactivate the certificate validation, the following setting must be made in
+To deactivate the certificate validation, the following setting must be added to
-[homserver.yaml](../usage/configuration/homeserver_sample_config.md).
+your [homserver.yaml](../usage/configuration/homeserver_sample_config.md).
 
 ```yaml
 use_insecure_ssl_client_just_for_testing_do_not_use: true

docs/setup/installation.md

@@ -407,11 +407,11 @@ The recommended way to do so is to set up a reverse proxy on port
 Alternatively, you can configure Synapse to expose an HTTPS port. To do
 so, you will need to edit `homeserver.yaml`, as follows:
 
-- First, under the `listeners` section, uncomment the configuration for the
+- First, under the `listeners` option, add the configuration for the
-  TLS-enabled listener. (Remove the hash sign (`#`) at the start of
+  TLS-enabled listener like so:
-  each line). The relevant lines are like this:
 
 ```yaml
+listeners:
   - port: 8448
     type: http
     tls: true
@@ -419,9 +419,11 @@ so, you will need to edit `homeserver.yaml`, as follows:
       - names: [client, federation]
   ```
 
-- You will also need to uncomment the `tls_certificate_path` and
+- You will also need to add the options `tls_certificate_path` and
-  `tls_private_key_path` lines under the `TLS` section. You will need to manage
+  `tls_private_key_path`. to your configuration file. You will need to manage provisioning of 
-  provisioning of these certificates yourself.
+   these certificates yourself.
+- You can find more information about these options as well as how to configure synapse in the 
+  [configuration manual](../usage/configuration/config_documentation.md).
 
   If you are using your own certificate, be sure to use a `.pem` file that
   includes the full certificate chain including any intermediate certificates

docs/usage/configuration/config_documentation.md

@@ -2999,7 +2999,7 @@ This setting has the following sub-options:
 * `localdb_enabled`: Set to false to disable authentication against the local password
    database. This is ignored if `enabled` is false, and is only useful
    if you have other `password_providers`. Defaults to true. 
-* `pepper`: Set the value here to a secret random string for extra security. # Uncomment and change to a secret random string for extra security.
+* `pepper`: Set the value here to a secret random string for extra security.
    DO NOT CHANGE THIS AFTER INITIAL SETUP!
 * `policy`: Define and enforce a password policy, such as minimum lengths for passwords, etc. 
    Each parameter is optional. This is an implementation of MSC2000. Parameters are as follows:

docs/usage/configuration/user_authentication/single_sign_on/cas.md

@@ -4,5 +4,5 @@ Synapse supports authenticating users via the [Central Authentication
 Service protocol](https://en.wikipedia.org/wiki/Central_Authentication_Service)
 (CAS) natively.
 
-Please see the `cas_config` and `sso` sections of the [Synapse configuration
+Please see the [cas_config](../../../configuration/config_documentation.md#cas_config) and [sso](../../../configuration/config_documentation.md#sso)
-file](../../../configuration/homeserver_sample_config.md) for more details.
+sections of the configuration manual for more details.

synapse/config/emailconfig.py

@@ -145,7 +145,7 @@ class EmailConfig(Config):
             raise ConfigError(
                 'The config option "trust_identity_server_for_password_resets" '
                 'has been replaced by "account_threepid_delegate". '
-                "Please consult the sample config at docs/sample_config.yaml for "
+                "Please consult the configuration manual at docs/usage/configuration/config_documentation.md for "
                 "details and update your config file."
             )