Machine-readable config description

[V02460]

Adds a JSON Schema description of the Synapse configuration to the repo, together with a script generating docs/usage/config_documentation.md from it.

This has many advantages, one can:

• Validate Synapse configuration files against the schema.
• Keep configuration and its documentation closer together, avoiding de-synchronization.
• Keep a uniform documentation style.
• Represent enforeable constraints between config values.
• Choose to reduce the amount of hand-rolled config validation code.
• Have IDE support like keyword suggestion and linting when editing a Synapse configuration.

I was surprised how aligned the expressiveness of the schema file is with the current infos from the Synapse documentation. Besides added types and defaults, some whitespace differences, and minor changes to wording and ordering, the config documentation remains mostly unchanged. But still, it is no perfect match, with the most important restrictions being:

1. No native sections for config options (the script patches those in).
2. No comments in examples. Might be handled as part of the description.
3. No native JSON Schema keyword representing the “Added in Synapse <version>” annotations (added to the plain-text description).

I expect there will be some feedback to work into this MR before it can get merged. I’m especially thinking about CI integration, JSON Schema IDs, types and defaults, and discussions about workflow – as well as a good amount of fixes due to the size of the change. Looking forward to your comments :)

Example

Running the script

scripts-dev/gen_config_documentation.py schemas/synapse-config.schema.json > docs/usage/configuration/config_documentation.md

on a schema containing the following fragment

"soft_file_limit": {
  "type": "integer",
  "description": "Set the soft limit on the number of file descriptors synapse can use. Zero is used to indicate synapse should set the soft limit to the hard limit.",
  "default": 0,
  "examples": [3]
}

yields the corresponding Synapse documentation as Markdown:

### `soft_file_limit`

*(integer)* Set the soft limit on the number of file descriptors synapse can
use. Zero is used to indicate synapse should set the soft limit to the hard
limit. Defaults to `0`.

Example configuration:
```yaml
soft_file_limit: 3
```

Pull Request Checklist

• Pull request is based on the develop branch
• Pull request includes a changelog file. The entry should:
  • Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
  • Use markdown where necessary, mostly for code blocks.
  • End with either a period (.) or an exclamation mark (!).
  • Start with a capital letter.
  • Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry.
• Code style is correct
  (run the linters)

[CLAassistant]

All committers have signed the CLA.