Fixes https://github.com/matrix-org/matrix-doc/issues/1166
Fixes https://github.com/matrix-org/matrix-doc/issues/1527
Fixes https://github.com/matrix-org/matrix-doc/issues/1827
Note: In order to fix the "state events have the following fields: [no words]" bug (1827) we need to resolve references on common event types. When doing this we ultimately end up with more fields than may be required to explain the section, however this commit alters the section descriptions to just say "these fields" instead of "these additional fields".
This is also preferable over trying to get the inheritance reversed in the common event types, as the `/sync` endpoint has a high amount of reliance on partial events definitions.
As per [MSC1452](https://github.com/matrix-org/matrix-doc/issues/1452)
Fixes https://github.com/matrix-org/matrix-doc/issues/1254
Although MSC1452 focuses on just the warnings part of the server notices, the base for notices has not been established in the spec. This commit adds the needed support to be able to handle notices.
No intentional divergences from the proposal are included in this changeset. There are a few additions which are used in practice although not defined in the proposal, such as who is responsible for aesthetics, sending notices, and other misc rules.
Previously the section was very strict in what pagination was, however this isn't the reality for the matrix specification. Several endpoints have their own pagination naming conventions and do not follow those mandated by this section.
This commit generalizes the language to cover those endpoints while also describing how pagination works. In particular, it describes the rough API shape to expect and how to deal with the responses.
This commit also removes the `M_BAD_PAGINATION` error as it is not used in the real world. Homeservers are instead encouraged to use the standard `M_INVALID_PARAM` or similar error code.
Fixes https://github.com/matrix-org/matrix-doc/issues/610
Fixes https://github.com/matrix-org/matrix-doc/issues/1523
Fixes https://github.com/matrix-org/matrix-doc/issues/1499
This is done by using magic variables in the RST. The magic variables are generated based on the substitutions available, making them available for use at build-time.
Magic variables were chosen because it allows people to continue working on the spec and release process without having to worry about removing a chunk of text from the top of the file. Originally, this was attempted by using jinja2 if-statements, however the substitutions are replaced *after* the template is executed, so the condition would never match.
The format of the variable is to make the templating happy. Using colons or percent signs results in the templator thinking something else is going on, and then complaining about format.
Travis Ralston