dandri/synapse
1
0
Fork 0
mirror of https://github.com/element-hq/synapse.git synced 2026-07-28 16:30:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

deploy: 8330fc9953

Browse Source
This commit is contained in:
H-Shay
2022-06-30 16:22:17 +00:00
parent b2e64bdcdd
commit 843e51823d
13 changed files with 134 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files
develop/code_style.html
+31 -66
View File
@@ -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
<p>The name of the option, prefixed by <code>###</code>. </p>
</li>
<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>
</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 &quot;Uncomment the following to enable [or disable]
<feature>.&quot; 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>&quot;</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