@@ -70,82 +70,61 @@ on save as they take a while and can be very resource intensive.
7070 - Avoid wildcard imports (`from synapse.types import * ` ) and
7171 relative imports (`from .types import UserID` ).
7272
73- # # Configuration file format
73+ # # Configuration code and documentation format
7474
75- The [sample configuration file ](./ sample_config.yaml) acts as a
75+ When adding a configuration option to the code, if several settings are grouped into a single dict , ensure that your code
76+ correctly handles the top- level option being set to `None ` (as it will be if no sub- options are enabled).
77+
78+ The [configuration manual](usage/ configuration/ config_documentation.md) acts as a
7679reference to Synapse' s configuration options for server administrators.
7780Remember that many readers will be unfamiliar with YAML and server
78- administration in general, so that it is important that the file be as
79- easy to understand as possible, which includes following a consistent
80- format .
81+ administration in general, so it is important that when you add
82+ a configuration option the documentation be as easy to understand as possible, which
83+ includes following a consistent format .
8184
8285Some guidelines follow:
8386
84- - Sections should be separated with a heading consisting of a single
85- line prefixed and suffixed with `# #`. There should be **two** blank
86- lines before the section header, and ** one** after.
87- - Each option should be listed in the file with the following format :
88- - A comment describing the setting. Each line of this comment
89- should be prefixed with a hash (`# `) and a space.
87+ - Each option should be listed in the config manual with the following format :
88+
89+ - The name of the option, prefixed by `# ##`.
9090
91- The comment should describe the default behaviour (ie, what
91+ - A comment which describes the default behaviour (i.e. what
9292 happens if the setting is omitted), as well as what the effect
9393 will be if the setting is changed.
94-
95- Often, the comment end with something like " uncomment the
96- following to < do action> " .
97-
98- - A line consisting of only `# `.
99- - A commented- out example setting, prefixed with only `# `.
94+ - An example setting, using backticks to define the code block
10095
10196 For boolean (on/ off) options, convention is that this example
102- should be the * opposite* to the default (so the comment will end
103- with " Uncomment the following to enable [or disable]
104- < feature> ." For other options, the example should give some
105- non- default value which is likely to be useful to the reader.
106-
107- - There should be a blank line between each option.
108- - Where several settings are grouped into a single dict , * avoid* the
109- convention where the whole block is commented out, resulting in
110- comment lines starting `# #`, as this is hard to read and confusing
111- to edit. Instead, leave the top- level config option uncommented, and
112- follow the conventions above for sub- options. Ensure that your code
113- correctly handles the top- level option being set to `None ` (as it
114- will be if no sub- options are enabled).
115- - Lines should be wrapped at 80 characters.
116- - Use two- space indents.
117- - `true` and `false` are spelt thus (as opposed to `True ` , etc.)
118- - Use single quotes (`' `) rather than double-quotes (`"`) or backticks
119- (`` ` ``) to refer to configuration options.
97+ should be the * opposite* to the default. For other options, the example should give
98+ some non- default value which is likely to be useful to the reader.
99+
100+ - There should be a horizontal rule between each option, which can be achieved by adding `-- - ` before and
101+ after the option.
102+ - `true` and `false` are spelt thus (as opposed to `True ` , etc.)
120103
121104Example:
122105
106+ -- -
107+ # ## `modules`
108+
109+ Use the `module` sub- option to add a module under `modules` to extend functionality.
110+ The `module` setting then has a sub- option, `config` , which can be used to define some configuration
111+ for the `module` .
112+
113+ Defaults to none.
114+
115+ Example configuration:
123116```yaml
124- # # Frobnication ##
125-
126- # The frobnicator will ensure that all requests are fully frobnicated.
127- # To enable it, uncomment the following.
128- #
129- # frobnicator_enabled: true
130-
131- # By default, the frobnicator will frobnicate with the default frobber.
132- # The following will make it use an alternative frobber.
133- #
134- # frobincator_frobber: special_frobber
135-
136- # Settings for the frobber
137- #
138- frobber:
139- # frobbing speed. Defaults to 1.
140- #
141- # speed: 10
142-
143- # frobbing distance. Defaults to 1000.
144- #
145- # distance: 100
117+ modules:
118+ - module: my_super_module.MySuperClass
119+ config:
120+ do_thing: true
121+ - module: my_other_super_module.SomeClass
122+ config: {}
146123```
124+ -- -
147125
148126Note that the sample configuration is generated from the synapse code
149127and is maintained by a script, `scripts- dev/ generate_sample_config.sh` .
150128Making sure that the output from this script matches the desired format
151129is left as an exercise for the reader!
130+
0 commit comments