deploy: 8330fc9953

develop/admin_api/user_admin_api.html

@@ -258,9 +258,8 @@ belonging to a user.</li>
 </ul>
 </li>
 <li><code>external_ids</code> - 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
-<a href="../usage/configuration/homeserver_sample_config.html">Sample Configuration File</a>
+sections <a href="../usage/configuration/config_documentation.html#sso">sso</a> and <a href="../usage/configuration/config_documentation.html#oidc_providers">oidc_providers</a>.
-section <code>sso</code> and <code>oidc_providers</code>.
 <ul>
 <li><code>auth_provider</code> - string. ID of the external identity provider. Value of <code>idp_id</code>
 in the homeserver configuration. Note that no error is raised if the provided

develop/code_style.html

@@ -211,95 +211,60 @@ relative imports (<code>from .types import UserID</code>).</p>
 </ul>
 </li>
 </ul>
-<h2 id="configuration-file-format"><a class="header" href="#configuration-file-format">Configuration file format</a></h2>
+<h2 id="configuration-code-and-documentation-format"><a class="header" href="#configuration-code-and-documentation-format">Configuration code and documentation format</a></h2>
-<p>The <a href="./sample_config.yaml">sample configuration file</a> acts as a
+<p>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 <code>None</code> (as it will be if no sub-options are enabled).</p>
+<p>The <a href="usage/configuration/config_documentation.html">configuration manual</a> 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.</p>
+includes following a consistent format.</p>
 <p>Some guidelines follow:</p>
 <ul>
 <li>
-<p>Sections should be separated with a heading consisting of a single
+<p>Each option should be listed in the config manual with the following format:</p>
-line prefixed and suffixed with <code>##</code>. There should be <strong>two</strong> blank
-lines before the section header, and <strong>one</strong> after.</p>
-</li>
-<li>
-<p>Each option should be listed in the file with the following format:</p>
 <ul>
 <li>
-<p>A comment describing the setting. Each line of this comment
+<p>The name of the option, prefixed by <code>###</code>. </p>
-should be prefixed with a hash (<code>#</code>) and a space.</p>
+</li>
-<p>The comment should describe the default behaviour (ie, what
+<li>
+<p>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.</p>
-<p>Often, the comment end with something like &quot;uncomment the
-following to <do action>&quot;.</p>
 </li>
 <li>
-<p>A line consisting of only <code>#</code>.</p>
+<p>An example setting, using backticks to define the code block</p>
-</li>
-<li>
-<p>A commented-out example setting, prefixed with only <code>#</code>.</p>
 <p>For boolean (on/off) options, convention is that this example
-should be the <em>opposite</em> to the default (so the comment will end
+should be the <em>opposite</em> to the default. For other options, the example should give
-with &quot;Uncomment the following to enable [or disable]
+some non-default value which is likely to be useful to the reader.</p>
-<feature>.&quot; For other options, the example should give some
-non-default value which is likely to be useful to the reader.</p>
 </li>
 </ul>
 </li>
 <li>
-<p>There should be a blank line between each option.</p>
+<p>There should be a horizontal rule between each option, which can be achieved by adding <code>---</code> before and
-</li>
+after the option.</p>
-<li>
-<p>Where several settings are grouped into a single dict, <em>avoid</em> the
-convention where the whole block is commented out, resulting in
-comment lines starting <code># #</code>, 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 <code>None</code> (as it
-will be if no sub-options are enabled).</p>
-</li>
-<li>
-<p>Lines should be wrapped at 80 characters.</p>
-</li>
-<li>
-<p>Use two-space indents.</p>
 </li>
 <li>
 <p><code>true</code> and <code>false</code> are spelt thus (as opposed to <code>True</code>, etc.)</p>
 </li>
-<li>
-<p>Use single quotes (<code>'</code>) rather than double-quotes (<code>&quot;</code>) or backticks
-(<code>`</code>) to refer to configuration options.</p>
-</li>
 </ul>
 <p>Example:</p>
-<pre><code class="language-yaml">## Frobnication ##
+<hr />
-
+<h3 id="modules"><a class="header" href="#modules"><code>modules</code></a></h3>
-# The frobnicator will ensure that all requests are fully frobnicated.
+<p>Use the <code>module</code> sub-option to add a module under <code>modules</code> to extend functionality. 
-# To enable it, uncomment the following.
+The <code>module</code> setting then has a sub-option, <code>config</code>, which can be used to define some configuration
-#
+for the <code>module</code>.</p>
-#frobnicator_enabled: true
+<p>Defaults to none.</p>
-
+<p>Example configuration:</p>
-# By default, the frobnicator will frobnicate with the default frobber.
+<pre><code class="language-yaml">modules:
-# The following will make it use an alternative frobber.
+  - module: my_super_module.MySuperClass
-#
+    config:
-#frobincator_frobber: special_frobber
+      do_thing: true
-
+  - module: my_other_super_module.SomeClass
-# Settings for the frobber
+    config: {}
-#
-frobber:
-  # frobbing speed. Defaults to 1.
-  #
-  #speed: 10
-
-  # frobbing distance. Defaults to 1000.
-  #
-  #distance: 100
 </code></pre>
+<hr />
 <p>Note that the sample configuration is generated from the synapse code
 and is maintained by a script, <code>scripts-dev/generate_sample_config.sh</code>.
 Making sure that the output from this script matches the desired format

develop/jwt.html

@@ -192,9 +192,8 @@ provided by <code>matrix.org</code> so no further action is needed.</p>
 maintainer.</p>
 </li>
 </ul>
-<p>To enable the JSON web token integration, you should then add a <code>jwt_config</code> section
+<p>To enable the JSON web token integration, you should then add a <code>jwt_config</code> option
-to your configuration file (or uncomment the <code>enabled: true</code> line in the
+to your configuration file. See the <a href="usage/configuration/config_documentation.html#jwt_config">configuration manual</a> for some
-existing section). See <a href="./sample_config.yaml">sample_config.yaml</a> for some
 sample settings.</p>
 <h2 id="how-to-test-jwt-as-a-developer"><a class="header" href="#how-to-test-jwt-as-a-developer">How to test JWT as a developer</a></h2>
 <p>Although JSON Web Tokens are typically generated from an external server, the

develop/manhole.html

@@ -155,8 +155,10 @@ debugging.</p>
 shell access to the server. It should therefore <strong>not</strong> be enabled in
 environments where untrusted users have shell access.</p>
 <h2 id="configuring-the-manhole"><a class="header" href="#configuring-the-manhole">Configuring the manhole</a></h2>
-<p>To enable it, first uncomment the <code>manhole</code> listener configuration in
+<p>To enable it, first add the <code>manhole</code> listener configuration in your
-<code>homeserver.yaml</code>. The configuration is slightly different if you're using docker.</p>
+<code>homeserver.yaml</code>. You can find information on how to do that 
+in the <a href="usage/configuration/config_documentation.html#manhole_settings">configuration manual</a>.
+The configuration is slightly different if you're using docker.</p>
 <h4 id="docker-config"><a class="header" href="#docker-config">Docker config</a></h4>
 <p>If you are using Docker, set <code>bind_addresses</code> to <code>['0.0.0.0']</code> as shown:</p>
 <pre><code class="language-yaml">listeners:

develop/message_retention_policies.html

@@ -186,9 +186,9 @@ though it will always hide it from clients.</p>
 delete the last message in a room. It will, however, hide it from
 clients.</p>
 <h2 id="server-configuration"><a class="header" href="#server-configuration">Server configuration</a></h2>
-<p>Support for this feature can be enabled and configured in the
+<p>Support for this feature can be enabled and configured by adding a the
-<code>retention</code> section of the Synapse configuration file (see the
+<code>retention</code> in the Synapse configuration file (see
-<a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample file</a>).</p>
+<a href="usage/configuration/config_documentation.html#retention">configuration manual</a>).</p>
 <p>To enable support for message retention policies, set the setting
 <code>enabled</code> in this section to <code>true</code>.</p>
 <h3 id="default-policy"><a class="header" href="#default-policy">Default policy</a></h3>
@@ -197,8 +197,8 @@ configuration that is used by Synapse for every room that doesn't have a
 message retention policy configured in its state. This allows server
 admins to ensure that messages are never kept indefinitely in a server's
 database. </p>
-<p>A default policy can be defined as such, in the <code>retention</code> section of
+<p>A default policy can be defined as such, by adding the <code>retention</code> option in
-the configuration file:</p>
+the configuration file and adding these sub-options:</p>
 <pre><code class="language-yaml">default_policy:
   min_lifetime: 1d
   max_lifetime: 1y
@@ -212,8 +212,8 @@ duration (using the units <code>s</code> (seconds), <code>m</code> (minutes), <c
 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
-<a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample configuration file</a>.</p>
+<a href="usage/configuration/config_documentation.html#retention">configuration manual</a>.</p>
 <p>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
 <code>purge_jobs</code> sub-section in the <code>retention</code> section of the configuration
@@ -254,8 +254,8 @@ local users between its expiry date and the moment it gets purged from
 the server's database.</p>
 <h3 id="lifetime-limits"><a class="header" href="#lifetime-limits">Lifetime limits</a></h3>
 <p>Server admins can set limits on the values of <code>max_lifetime</code> 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
-<code>retention</code> section of the configuration file:</p>
+<code>retention</code> option in the configuration file:</p>
 <pre><code class="language-yaml">allowed_lifetime_min: 1d
 allowed_lifetime_max: 1y
 </code></pre>

develop/openid.html

@@ -185,8 +185,8 @@ maintainer.</p>
 </li>
 </ul>
 <p>To enable the OpenID integration, you should then add a section to the <code>oidc_providers</code>
-setting in your configuration file (or uncomment one of the existing examples).
+setting in your configuration file.
-See <a href="./sample_config.yaml">sample_config.yaml</a> for some sample settings, as well as
+See the <a href="usage/configuration/config_documentation.html#oidc_providers">configuration manual</a> for some sample settings, as well as
 the text below for example configurations for specific providers.</p>
 <h2 id="sample-configs"><a class="header" href="#sample-configs">Sample configs</a></h2>
 <p>Here are a few configs for providers that should work with Synapse.</p>

develop/print.html

@@ -503,11 +503,11 @@ over HTTPS.</p>
 <p>Alternatively, you can configure Synapse to expose an HTTPS port. To do
 so, you will need to edit <code>homeserver.yaml</code>, as follows:</p>
 <ul>
-<li>First, under the <code>listeners</code> section, uncomment the configuration for the
+<li>First, under the <code>listeners</code> option, add the configuration for the
-TLS-enabled listener. (Remove the hash sign (<code>#</code>) at the start of
+TLS-enabled listener like so:</li>
-each line). The relevant lines are like this:</li>
 </ul>
-<pre><code class="language-yaml">  - port: 8448
+<pre><code class="language-yaml">listeners:
+  - port: 8448
     type: http
     tls: true
     resources:
@@ -515,9 +515,13 @@ each line). The relevant lines are like this:</li>
 </code></pre>
 <ul>
 <li>
-<p>You will also need to uncomment the <code>tls_certificate_path</code> and
+<p>You will also need to add the options <code>tls_certificate_path</code> and
-<code>tls_private_key_path</code> lines under the <code>TLS</code> section. You will need to manage
+<code>tls_private_key_path</code>. to your configuration file. You will need to manage provisioning of 
-provisioning of these certificates yourself.</p>
+these certificates yourself.</p>
+</li>
+<li>
+<p>You can find more information about these options as well as how to configure synapse in the 
+<a href="setup/../usage/configuration/config_documentation.html">configuration manual</a>.</p>
 <p>If you are using your own certificate, be sure to use a <code>.pem</code> file that
 includes the full certificate chain including any intermediate certificates
 (for instance, if using certbot, use <code>fullchain.pem</code> as your certificate, not
@@ -1149,8 +1153,8 @@ will apply blacklisting of IP addresses.</p>
 it is most likely due to the proxy's certificates. To test this, the validation
 in Synapse can be deactivated.</p>
 <p><strong>NOTE</strong>: This has an impact on security and is for testing purposes only!</p>
-<p>To deactivate the certificate validation, the following setting must be made in
+<p>To deactivate the certificate validation, the following setting must be added to
-<a href="setup/../usage/configuration/homeserver_sample_config.html">homserver.yaml</a>.</p>
+your <a href="setup/../usage/configuration/homeserver_sample_config.html">homserver.yaml</a>.</p>
 <pre><code class="language-yaml">use_insecure_ssl_client_just_for_testing_do_not_use: true
 </code></pre>
 <div style="break-before: page; page-break-before: always;"></div><h1 id="overview-1"><a class="header" href="#overview-1">Overview</a></h1>
@@ -5649,7 +5653,7 @@ to log in and reauthenticate, whilst preventing new users from setting passwords
 <li><code>localdb_enabled</code>: Set to false to disable authentication against the local password
 database. This is ignored if <code>enabled</code> is false, and is only useful
 if you have other <code>password_providers</code>. Defaults to true. </li>
-<li><code>pepper</code>: Set the value here to a secret random string for extra security. # Uncomment and change to a secret random string for extra security.
+<li><code>pepper</code>: Set the value here to a secret random string for extra security.
 DO NOT CHANGE THIS AFTER INITIAL SETUP!</li>
 <li><code>policy</code>: 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:
@@ -6753,8 +6757,8 @@ maintainer.</p>
 </li>
 </ul>
 <p>To enable the OpenID integration, you should then add a section to the <code>oidc_providers</code>
-setting in your configuration file (or uncomment one of the existing examples).
+setting in your configuration file.
-See <a href="./sample_config.yaml">sample_config.yaml</a> for some sample settings, as well as
+See the <a href="usage/configuration/config_documentation.html#oidc_providers">configuration manual</a> for some sample settings, as well as
 the text below for example configurations for specific providers.</p>
 <h2 id="sample-configs"><a class="header" href="#sample-configs">Sample configs</a></h2>
 <p>Here are a few configs for providers that should work with Synapse.</p>
@@ -7243,8 +7247,8 @@ file</a> for more details.</p>
 <p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Central_Authentication_Service">Central Authentication
 Service protocol</a>
 (CAS) natively.</p>
-<p>Please see the <code>cas_config</code> and <code>sso</code> sections of the <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/homeserver_sample_config.html">Synapse configuration
+<p>Please see the <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/config_documentation.html#cas_config">cas_config</a> and <a href="usage/configuration/user_authentication/single_sign_on/../../../configuration/config_documentation.html#sso">sso</a>
-file</a> for more details.</p>
+sections of the configuration manual for more details.</p>
 <div style="break-before: page; page-break-before: always;"></div><h1 id="sso-mapping-providers"><a class="header" href="#sso-mapping-providers">SSO Mapping Providers</a></h1>
 <p>A mapping provider is a Python class (loaded via a Python module) that
 works out how to map attributes of a SSO response to Matrix-specific
@@ -7654,9 +7658,8 @@ provided by <code>matrix.org</code> so no further action is needed.</p>
 maintainer.</p>
 </li>
 </ul>
-<p>To enable the JSON web token integration, you should then add a <code>jwt_config</code> section
+<p>To enable the JSON web token integration, you should then add a <code>jwt_config</code> option
-to your configuration file (or uncomment the <code>enabled: true</code> line in the
+to your configuration file. See the <a href="usage/configuration/config_documentation.html#jwt_config">configuration manual</a> for some
-existing section). See <a href="./sample_config.yaml">sample_config.yaml</a> for some
 sample settings.</p>
 <h2 id="how-to-test-jwt-as-a-developer"><a class="header" href="#how-to-test-jwt-as-a-developer">How to test JWT as a developer</a></h2>
 <p>Although JSON Web Tokens are typically generated from an external server, the
@@ -8272,9 +8275,9 @@ though it will always hide it from clients.</p>
 delete the last message in a room. It will, however, hide it from
 clients.</p>
 <h2 id="server-configuration"><a class="header" href="#server-configuration">Server configuration</a></h2>
-<p>Support for this feature can be enabled and configured in the
+<p>Support for this feature can be enabled and configured by adding a the
-<code>retention</code> section of the Synapse configuration file (see the
+<code>retention</code> in the Synapse configuration file (see
-<a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample file</a>).</p>
+<a href="usage/configuration/config_documentation.html#retention">configuration manual</a>).</p>
 <p>To enable support for message retention policies, set the setting
 <code>enabled</code> in this section to <code>true</code>.</p>
 <h3 id="default-policy"><a class="header" href="#default-policy">Default policy</a></h3>
@@ -8283,8 +8286,8 @@ configuration that is used by Synapse for every room that doesn't have a
 message retention policy configured in its state. This allows server
 admins to ensure that messages are never kept indefinitely in a server's
 database. </p>
-<p>A default policy can be defined as such, in the <code>retention</code> section of
+<p>A default policy can be defined as such, by adding the <code>retention</code> option in
-the configuration file:</p>
+the configuration file and adding these sub-options:</p>
 <pre><code class="language-yaml">default_policy:
   min_lifetime: 1d
   max_lifetime: 1y
@@ -8298,8 +8301,8 @@ duration (using the units <code>s</code> (seconds), <code>m</code> (minutes), <c
 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
-<a href="https://github.com/matrix-org/synapse/blob/v1.36.0/docs/sample_config.yaml#L451-L518">sample configuration file</a>.</p>
+<a href="usage/configuration/config_documentation.html#retention">configuration manual</a>.</p>
 <p>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
 <code>purge_jobs</code> sub-section in the <code>retention</code> section of the configuration
@@ -8340,8 +8343,8 @@ local users between its expiry date and the moment it gets purged from
 the server's database.</p>
 <h3 id="lifetime-limits"><a class="header" href="#lifetime-limits">Lifetime limits</a></h3>
 <p>Server admins can set limits on the values of <code>max_lifetime</code> 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
-<code>retention</code> section of the configuration file:</p>
+<code>retention</code> option in the configuration file:</p>
 <pre><code class="language-yaml">allowed_lifetime_min: 1d
 allowed_lifetime_max: 1y
 </code></pre>
@@ -12123,9 +12126,8 @@ belonging to a user.</li>
 </ul>
 </li>
 <li><code>external_ids</code> - 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
-<a href="admin_api/../usage/configuration/homeserver_sample_config.html">Sample Configuration File</a>
+sections <a href="admin_api/../usage/configuration/config_documentation.html#sso">sso</a> and <a href="admin_api/../usage/configuration/config_documentation.html#oidc_providers">oidc_providers</a>.
-section <code>sso</code> and <code>oidc_providers</code>.
 <ul>
 <li><code>auth_provider</code> - string. ID of the external identity provider. Value of <code>idp_id</code>
 in the homeserver configuration. Note that no error is raised if the provided
@@ -13187,8 +13189,10 @@ debugging.</p>
 shell access to the server. It should therefore <strong>not</strong> be enabled in
 environments where untrusted users have shell access.</p>
 <h2 id="configuring-the-manhole"><a class="header" href="#configuring-the-manhole">Configuring the manhole</a></h2>
-<p>To enable it, first uncomment the <code>manhole</code> listener configuration in
+<p>To enable it, first add the <code>manhole</code> listener configuration in your
-<code>homeserver.yaml</code>. The configuration is slightly different if you're using docker.</p>
+<code>homeserver.yaml</code>. You can find information on how to do that 
+in the <a href="usage/configuration/config_documentation.html#manhole_settings">configuration manual</a>.
+The configuration is slightly different if you're using docker.</p>
 <h4 id="docker-config"><a class="header" href="#docker-config">Docker config</a></h4>
 <p>If you are using Docker, set <code>bind_addresses</code> to <code>['0.0.0.0']</code> as shown:</p>
 <pre><code class="language-yaml">listeners:
@@ -14290,95 +14294,60 @@ relative imports (<code>from .types import UserID</code>).</p>
 </ul>
 </li>
 </ul>
-<h2 id="configuration-file-format"><a class="header" href="#configuration-file-format">Configuration file format</a></h2>
+<h2 id="configuration-code-and-documentation-format"><a class="header" href="#configuration-code-and-documentation-format">Configuration code and documentation format</a></h2>
-<p>The <a href="./sample_config.yaml">sample configuration file</a> acts as a
+<p>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 <code>None</code> (as it will be if no sub-options are enabled).</p>
+<p>The <a href="usage/configuration/config_documentation.html">configuration manual</a> 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.</p>
+includes following a consistent format.</p>
 <p>Some guidelines follow:</p>
 <ul>
 <li>
-<p>Sections should be separated with a heading consisting of a single
+<p>Each option should be listed in the config manual with the following format:</p>
-line prefixed and suffixed with <code>##</code>. There should be <strong>two</strong> blank
-lines before the section header, and <strong>one</strong> after.</p>
-</li>
-<li>
-<p>Each option should be listed in the file with the following format:</p>
 <ul>
 <li>
-<p>A comment describing the setting. Each line of this comment
+<p>The name of the option, prefixed by <code>###</code>. </p>
-should be prefixed with a hash (<code>#</code>) and a space.</p>
+</li>
-<p>The comment should describe the default behaviour (ie, what
+<li>
+<p>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.</p>
-<p>Often, the comment end with something like &quot;uncomment the
-following to <do action>&quot;.</p>
 </li>
 <li>
-<p>A line consisting of only <code>#</code>.</p>
+<p>An example setting, using backticks to define the code block</p>
-</li>
-<li>
-<p>A commented-out example setting, prefixed with only <code>#</code>.</p>
 <p>For boolean (on/off) options, convention is that this example
-should be the <em>opposite</em> to the default (so the comment will end
+should be the <em>opposite</em> to the default. For other options, the example should give
-with &quot;Uncomment the following to enable [or disable]
+some non-default value which is likely to be useful to the reader.</p>
-<feature>.&quot; For other options, the example should give some
-non-default value which is likely to be useful to the reader.</p>
 </li>
 </ul>
 </li>
 <li>
-<p>There should be a blank line between each option.</p>
+<p>There should be a horizontal rule between each option, which can be achieved by adding <code>---</code> before and
-</li>
+after the option.</p>
-<li>
-<p>Where several settings are grouped into a single dict, <em>avoid</em> the
-convention where the whole block is commented out, resulting in
-comment lines starting <code># #</code>, 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 <code>None</code> (as it
-will be if no sub-options are enabled).</p>
-</li>
-<li>
-<p>Lines should be wrapped at 80 characters.</p>
-</li>
-<li>
-<p>Use two-space indents.</p>
 </li>
 <li>
 <p><code>true</code> and <code>false</code> are spelt thus (as opposed to <code>True</code>, etc.)</p>
 </li>
-<li>
-<p>Use single quotes (<code>'</code>) rather than double-quotes (<code>&quot;</code>) or backticks
-(<code>`</code>) to refer to configuration options.</p>
-</li>
 </ul>
 <p>Example:</p>
-<pre><code class="language-yaml">## Frobnication ##
+<hr />
-
+<h3 id="modules-3"><a class="header" href="#modules-3"><code>modules</code></a></h3>
-# The frobnicator will ensure that all requests are fully frobnicated.
+<p>Use the <code>module</code> sub-option to add a module under <code>modules</code> to extend functionality. 
-# To enable it, uncomment the following.
+The <code>module</code> setting then has a sub-option, <code>config</code>, which can be used to define some configuration
-#
+for the <code>module</code>.</p>
-#frobnicator_enabled: true
+<p>Defaults to none.</p>
-
+<p>Example configuration:</p>
-# By default, the frobnicator will frobnicate with the default frobber.
+<pre><code class="language-yaml">modules:
-# The following will make it use an alternative frobber.
+  - module: my_super_module.MySuperClass
-#
+    config:
-#frobincator_frobber: special_frobber
+      do_thing: true
-
+  - module: my_other_super_module.SomeClass
-# Settings for the frobber
+    config: {}
-#
-frobber:
-  # frobbing speed. Defaults to 1.
-  #
-  #speed: 10
-
-  # frobbing distance. Defaults to 1000.
-  #
-  #distance: 100
 </code></pre>
+<hr />
 <p>Note that the sample configuration is generated from the synapse code
 and is maintained by a script, <code>scripts-dev/generate_sample_config.sh</code>.
 Making sure that the output from this script matches the desired format

develop/setup/forward_proxy.html

@@ -217,8 +217,8 @@ will apply blacklisting of IP addresses.</p>
 it is most likely due to the proxy's certificates. To test this, the validation
 in Synapse can be deactivated.</p>
 <p><strong>NOTE</strong>: This has an impact on security and is for testing purposes only!</p>
-<p>To deactivate the certificate validation, the following setting must be made in
+<p>To deactivate the certificate validation, the following setting must be added to
-<a href="../usage/configuration/homeserver_sample_config.html">homserver.yaml</a>.</p>
+your <a href="../usage/configuration/homeserver_sample_config.html">homserver.yaml</a>.</p>
 <pre><code class="language-yaml">use_insecure_ssl_client_just_for_testing_do_not_use: true
 </code></pre>
 

develop/setup/installation.html

@@ -420,11 +420,11 @@ over HTTPS.</p>
 <p>Alternatively, you can configure Synapse to expose an HTTPS port. To do
 so, you will need to edit <code>homeserver.yaml</code>, as follows:</p>
 <ul>
-<li>First, under the <code>listeners</code> section, uncomment the configuration for the
+<li>First, under the <code>listeners</code> option, add the configuration for the
-TLS-enabled listener. (Remove the hash sign (<code>#</code>) at the start of
+TLS-enabled listener like so:</li>
-each line). The relevant lines are like this:</li>
 </ul>
-<pre><code class="language-yaml">  - port: 8448
+<pre><code class="language-yaml">listeners:
+  - port: 8448
     type: http
     tls: true
     resources:
@@ -432,9 +432,13 @@ each line). The relevant lines are like this:</li>
 </code></pre>
 <ul>
 <li>
-<p>You will also need to uncomment the <code>tls_certificate_path</code> and
+<p>You will also need to add the options <code>tls_certificate_path</code> and
-<code>tls_private_key_path</code> lines under the <code>TLS</code> section. You will need to manage
+<code>tls_private_key_path</code>. to your configuration file. You will need to manage provisioning of 
-provisioning of these certificates yourself.</p>
+these certificates yourself.</p>
+</li>
+<li>
+<p>You can find more information about these options as well as how to configure synapse in the 
+<a href="../usage/configuration/config_documentation.html">configuration manual</a>.</p>
 <p>If you are using your own certificate, be sure to use a <code>.pem</code> file that
 includes the full certificate chain including any intermediate certificates
 (for instance, if using certbot, use <code>fullchain.pem</code> as your certificate, not

develop/usage/configuration/config_documentation.html

@@ -2649,7 +2649,7 @@ to log in and reauthenticate, whilst preventing new users from setting passwords
 <li><code>localdb_enabled</code>: Set to false to disable authentication against the local password
 database. This is ignored if <code>enabled</code> is false, and is only useful
 if you have other <code>password_providers</code>. Defaults to true. </li>
-<li><code>pepper</code>: Set the value here to a secret random string for extra security. # Uncomment and change to a secret random string for extra security.
+<li><code>pepper</code>: Set the value here to a secret random string for extra security.
 DO NOT CHANGE THIS AFTER INITIAL SETUP!</li>
 <li><code>policy</code>: 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:

develop/usage/configuration/user_authentication/single_sign_on/cas.html

@@ -150,8 +150,8 @@
 <p>Synapse supports authenticating users via the <a href="https://en.wikipedia.org/wiki/Central_Authentication_Service">Central Authentication
 Service protocol</a>
 (CAS) natively.</p>
-<p>Please see the <code>cas_config</code> and <code>sso</code> sections of the <a href="../../../configuration/homeserver_sample_config.html">Synapse configuration
+<p>Please see the <a href="../../../configuration/config_documentation.html#cas_config">cas_config</a> and <a href="../../../configuration/config_documentation.html#sso">sso</a>
-file</a> for more details.</p>
+sections of the configuration manual for more details.</p>
 
                     </main>