From 6f1cfedad0d05265dfc487e13307cb9fa11b4564 Mon Sep 17 00:00:00 2001 From: Will Date: Wed, 27 Jan 2021 10:44:02 -0800 Subject: [PATCH] Remove RST alert directives, replace with simple Markdown formatting --- .../client-server/administrative_contact.yaml | 10 ++--- data/api/client-server/content-repo.yaml | 10 ++--- data/api/client-server/directory.yaml | 20 +++++----- data/api/server-server/backfill.yaml | 12 +++--- data/api/server-server/invites-v2.yaml | 6 +-- data/api/server-server/joins-v1.yaml | 7 ++-- data/api/server-server/joins-v2.yaml | 6 +-- data/api/server-server/leaving-v1.yaml | 5 +-- data/api/server-server/leaving-v2.yaml | 6 +-- .../schema/m.room.power_levels.yaml | 16 ++++---- .../schema/m.room.server_acl.yaml | 40 +++++++++---------- 11 files changed, 68 insertions(+), 70 deletions(-) diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index f8cdf5a0..61f9e8eb 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -96,11 +96,11 @@ paths: This endpoint is deprecated in favour of the more specific ``/3pid/add`` and ``/3pid/bind`` endpoints. - .. Note:: - Previously this endpoint supported a ``bind`` parameter. This parameter - has been removed, making this endpoint behave as though it was ``false``. - This results in this endpoint being an equivalent to ``/3pid/bind`` rather - than dual-purpose. + **Note:** + Previously this endpoint supported a ``bind`` parameter. This parameter + has been removed, making this endpoint behave as though it was ``false``. + This results in this endpoint being an equivalent to ``/3pid/bind`` rather + than dual-purpose. operationId: post3PIDs deprecated: true security: diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 38a739ec..b827e8d2 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -347,11 +347,11 @@ paths: Get information about a URL for the client. Typically this is called when a client sees a URL in a message and wants to render a preview for the user. - .. Note:: - Clients should consider avoiding this endpoint for URLs posted in encrypted - rooms. Encrypted rooms often contain more sensitive information the users - do not want to share with the homeserver, and this can mean that the URLs - being shared should also not be shared with the homeserver. + **Note:** + Clients should consider avoiding this endpoint for URLs posted in encrypted + rooms. Encrypted rooms often contain more sensitive information the users + do not want to share with the homeserver, and this can mean that the URLs + being shared should also not be shared with the homeserver. operationId: getUrlPreview produces: ["application/json"] diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml index 7a08faf2..f470c730 100644 --- a/data/api/client-server/directory.yaml +++ b/data/api/client-server/directory.yaml @@ -132,12 +132,12 @@ paths: Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator. - .. Note:: - Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias`` - state event in the room when an alias is removed. Servers which choose to update the - canonical alias event are recommended to, in addition to their other relevant permission - checks, delete the alias and return a successful response even if the user does not - have permission to update the ``m.room.canonical_alias`` event. + **Note:** + Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias`` + state event in the room when an alias is removed. Servers which choose to update the + canonical alias event are recommended to, in addition to their other relevant permission + checks, delete the alias and return a successful response even if the user does not + have permission to update the ``m.room.canonical_alias`` event. operationId: deleteRoomAlias security: @@ -184,10 +184,10 @@ paths: such as allowing server administrators to view aliases regardless of membership. - .. Note:: - Clients are recommended not to display this list of aliases prominently - as they are not curated, unlike those listed in the ``m.room.canonical_alias`` - state event. + **Note:** + Clients are recommended not to display this list of aliases prominently + as they are not curated, unlike those listed in the ``m.room.canonical_alias`` + state event. operationId: getLocalAliases security: diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml index 4bf62663..74067a80 100644 --- a/data/api/server-server/backfill.yaml +++ b/data/api/server-server/backfill.yaml @@ -64,13 +64,13 @@ paths: A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit. - .. Note:: - Though the PDU definitions require that ``prev_events`` and ``auth_events`` be limited - in number, the response of backfill MUST NOT be validated on these specific restrictions. + **Note:** + Though the PDU definitions require that ``prev_events`` and ``auth_events`` be limited + in number, the response of backfill MUST NOT be validated on these specific restrictions. - Due to historical reasons, it is possible that events which were previously accepted - would now be rejected by these limitations. The events should be rejected per usual by - the ``/send``, ``/get_missing_events``, and remaining endpoints. + Due to historical reasons, it is possible that events which were previously accepted + would now be rejected by these limitations. The events should be rejected per usual by + the ``/send``, ``/get_missing_events``, and remaining endpoints. schema: $ref: "definitions/unlimited_pdu_transaction.yaml" "/get_missing_events/{roomId}": diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 28cbccca..58d32049 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -31,9 +31,9 @@ paths: put: summary: Invites a remote user to a room description: |- - .. Note:: - This API is nearly identical to the v1 API with the exception of the request - body being different, and the response format fixed. + **Note:** + This API is nearly identical to the v1 API with the exception of the request + body being different, and the response format fixed. Invites a remote user to a room. Once the event has been signed by both the inviting homeserver and the invited homeserver, it can be sent to all of the servers in the diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index d4fc8f24..e9654cd8 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -171,14 +171,13 @@ paths: "errcode": "M_NOT_FOUND", "error": "Unknown room", } - + "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server description: |- - .. Note:: - Servers should instead prefer to use the v2 ``/send_join`` - endpoint. + **Note:** + Servers should instead prefer to use the v2 ``/send_join`` endpoint. Submits a signed join event to the resident server for it to accept it into the room's graph. Note that events have diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index b5a1544c..7f1d675e 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -33,9 +33,9 @@ paths: put: summary: Submit a signed join event to a resident server description: |- - .. Note:: - This API is nearly identical to the v1 API with the - exception of the response format being fixed. + **Note:** + This API is nearly identical to the v1 API with the + exception of the response format being fixed. This endpoint is preferred over the v1 API as it provides a more standarised response format. Senders which receive diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index c92b7920..ff12bbce 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -143,9 +143,8 @@ paths: put: summary: Submit a signed leave event to a resident server description: |- - .. Note:: - Servers should instead prefer to use the v2 ``/send_leave`` - endpoint. + **Note:** + Servers should instead prefer to use the v2 ``/send_leave`` endpoint. Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index 3e82c414..7069b6c0 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -33,9 +33,9 @@ paths: put: summary: Submit a signed leave event to a resident server description: |- - .. Note:: - This API is nearly identical to the v1 API with the - exception of the response format being fixed. + **Note:** + This API is nearly identical to the v1 API with the + exception of the response format being fixed. This endpoint is preferred over the v1 API as it provides a more standarised response format. Senders which receive diff --git a/data/event-schemas/schema/m.room.power_levels.yaml b/data/event-schemas/schema/m.room.power_levels.yaml index 8e94bcc0..6e026d6c 100644 --- a/data/event-schemas/schema/m.room.power_levels.yaml +++ b/data/event-schemas/schema/m.room.power_levels.yaml @@ -31,16 +31,16 @@ description: |- ``m.room.power_levels`` event, or if the room contains no ``m.room.power_levels`` event. - .. NOTE:: + **Note:** - As noted above, in the absence of an ``m.room.power_levels`` event, the - ``state_default`` is 0, and all users are considered to have power level 0. - That means that **any** member of the room can send an - ``m.room.power_levels`` event, changing the permissions in the room. + As noted above, in the absence of an ``m.room.power_levels`` event, the + ``state_default`` is 0, and all users are considered to have power level 0. + That means that **any** member of the room can send an + ``m.room.power_levels`` event, changing the permissions in the room. - Server implementations should therefore ensure that each room has an - ``m.room.power_levels`` event as soon as it is created. See also the - documentation of the ``/createRoom`` API. + Server implementations should therefore ensure that each room has an + ``m.room.power_levels`` event as soon as it is created. See also the + documentation of the ``/createRoom`` API. properties: content: diff --git a/data/event-schemas/schema/m.room.server_acl.yaml b/data/event-schemas/schema/m.room.server_acl.yaml index 86d83832..60424cc6 100644 --- a/data/event-schemas/schema/m.room.server_acl.yaml +++ b/data/event-schemas/schema/m.room.server_acl.yaml @@ -22,26 +22,26 @@ description: |- #. If the server name matches an entry in the ``allow`` list, allow. #. Otherwise, deny. - .. Note:: - Server ACLs do not restrict the events relative to the room DAG via authorisation - rules, but instead act purely at the network layer to determine which servers are - allowed to connect and interact with a given room. + **Note:** + Server ACLs do not restrict the events relative to the room DAG via authorisation + rules, but instead act purely at the network layer to determine which servers are + allowed to connect and interact with a given room. - .. WARNING:: - Failing to provide an ``allow`` rule of some kind will prevent **all** - servers from participating in the room, including the sender. This renders - the room unusable. A common allow rule is ``[ "*" ]`` which would still - permit the use of the ``deny`` list without losing the room. - - .. WARNING:: - All compliant servers must implement server ACLs. However, legacy or noncompliant - servers exist which do not uphold ACLs, and these MUST be manually appended to - the denied hosts list when setting an ACL to prevent them from leaking events from - banned servers into a room. Currently, the only way to determine noncompliant hosts is - to check the ``prev_events`` of leaked events, therefore detecting servers which - are not upholding the ACLs. Server versions can also be used to try to detect hosts that - will not uphold the ACLs, although this is not comprehensive. Server ACLs were added - in Synapse v0.32.0, although other server implementations and versions exist in the world. + **Warning:** + Failing to provide an ``allow`` rule of some kind will prevent **all** + servers from participating in the room, including the sender. This renders + the room unusable. A common allow rule is ``[ "*" ]`` which would still + permit the use of the ``deny`` list without losing the room. + + **Warning:** + All compliant servers must implement server ACLs. However, legacy or noncompliant + servers exist which do not uphold ACLs, and these MUST be manually appended to + the denied hosts list when setting an ACL to prevent them from leaking events from + banned servers into a room. Currently, the only way to determine noncompliant hosts is + to check the ``prev_events`` of leaked events, therefore detecting servers which + are not upholding the ACLs. Server versions can also be used to try to detect hosts that + will not uphold the ACLs, although this is not comprehensive. Server ACLs were added + in Synapse v0.32.0, although other server implementations and versions exist in the world. allOf: - $ref: core-event-schema/state_event.yaml type: object @@ -55,7 +55,7 @@ properties: deny. Defaults to true if missing or otherwise not a boolean. This is strongly recommended to be set to ``false`` as servers running - with IP literal names are strongly discouraged in order to require + with IP literal names are strongly discouraged in order to require legitimate homeservers to be backed by a valid registered domain name. allow: type: array