diff --git a/develop/code_style.html b/develop/code_style.html
index 6c0a59f4fe..8d7150fd3f 100644
--- a/develop/code_style.html
+++ b/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>
-<p>The <a href="./sample_config.yaml">sample configuration file</a> acts as a
+<h2 id="configuration-code-and-documentation-format"><a class="header" href="#configuration-code-and-documentation-format">Configuration code and documentation format</a></h2>
+<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
-easy to understand as possible, which includes following a consistent
-format.</p>
+administration in general, so it is important that when you add
+a configuration option the documentation be as easy to understand as possible, which
+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
-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>
+<p>Each option should be listed in the config manual with the following format:</p>
<ul>
<li>
-<p>A comment describing the setting. Each line of this comment
-should be prefixed with a hash (<code>#</code>) and a space.</p>
-<p>The comment should describe the default behaviour (ie, 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 "uncomment the
-following to <do action>".</p>
+<p>The name of the option, prefixed by <code>###</code>. </p>
</li>
<li>
-<p>A line consisting of only <code>#</code>.</p>
+<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>
</li>
<li>
-<p>A commented-out example setting, prefixed with only <code>#</code>.</p>
+<p>An example setting, using backticks to define the code block</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
-with "Uncomment the following to enable [or disable]
-<feature>." For other options, the example should give some
-non-default value which is likely to be useful to the reader.</p>
+should be the <em>opposite</em> to the default. 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>
-</li>
-<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>
+<p>There should be a horizontal rule between each option, which can be achieved by adding <code>---</code> before and
+after the option.</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>"</code>) or backticks
-(<code>`</code>) to refer to configuration options.</p>
-</li>
</ul>
<p>Example:</p>
-<pre><code class="language-yaml">## Frobnication ##
-
-# The frobnicator will ensure that all requests are fully frobnicated.
-# To enable it, uncomment the following.
-#
-#frobnicator_enabled: true
-
-# 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
+<hr />
+<h3 id="modules"><a class="header" href="#modules"><code>modules</code></a></h3>
+<p>Use the <code>module</code> sub-option to add a module under <code>modules</code> to extend functionality.
+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>
+<p>Defaults to none.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">modules:
+ - module: my_super_module.MySuperClass
+ config:
+ do_thing: true
+ - module: my_other_super_module.SomeClass
+ config: {}
</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
|
