Merge remote-tracking branch 'matrix-org/master' into travis/towncrier

.circleci/config.yml

@@ -0,0 +1,49 @@
+gendoc: &gendoc
+  name: Generate the docs
+  command: |
+    source /env/bin/activate
+    scripts/gendoc.py
+
+gendoc: &genswagger
+  name: Generate the swagger
+  command: |
+    source /env/bin/activate
+    scripts/dump-swagger.py
+
+version: 2
+jobs:
+  build-docs:
+    docker:
+      - image: uhoreg/matrix-doc-build
+    steps:
+      - checkout
+      - run: *gendoc
+      - store_artifacts:
+          path: scripts/gen
+      - run:
+          name: "Doc build is available at:"
+          command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/gen/index.html"; echo $DOCS_URL
+
+  build-swagger:
+    docker:
+      - image: uhoreg/matrix-doc-build
+    steps:
+      - checkout
+      - run: *genswagger
+      - store_artifacts:
+          path: scripts/swagger/api-docs.json
+      - run:
+          name: "Swagger UI is available at:"
+          command: SWAGGER_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/swagger/api-docs.json"; echo "https://matrix.org/docs/api/client-server/?url="$SWAGGER_URL
+
+workflows:
+  version: 2
+
+  build-spec:
+    jobs:
+      - build-docs
+      - build-swagger
+
+notify:
+  webhooks:
+    - url: https://giles.cadair.com/circleci

api/client-server/create_room.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -40,7 +41,7 @@ paths:
         0. A default ``m.room.power_levels`` event, giving the room creator
            (and not other members) permission to send state events.
         
-        1. Events set by ``presets``.
+        1. Events set by the ``preset``.
 
         2. Events listed in ``initial_state``, in the order that they are
            listed.
@@ -49,6 +50,16 @@ paths:
 
         4. Invite events implied by ``invite`` and ``invite_3pid``.
 
+        The available presets do the following with respect to room state:
+
+        ========================  ==============  ======================  ================  =========
+                 Preset           ``join_rules``  ``history_visibility``  ``guest_access``  Other
+        ========================  ==============  ======================  ================  =========
+        ``private_chat``          ``invite``      ``shared``              ``can_join``      
+        ``trusted_private_chat``  ``invite``      ``shared``              ``can_join``      All invitees are given the same power level as the room creator.
+        ``public_chat``           ``public``      ``shared``              ``forbidden``     
+        ========================  ==============  ======================  ================  =========
+
       operationId: createRoom
       security:
         - accessToken: []
@@ -142,7 +153,7 @@ paths:
                   room. The expected format of the state events are an object
                   with type, state_key and content keys set.
 
-                  Takes precedence over events set by ``presets``, but gets
+                  Takes precedence over events set by ``preset``, but gets
                   overriden by ``name`` and ``topic`` keys.
                 items:
                   type: object
@@ -163,20 +174,7 @@ paths:
                 enum: ["private_chat", "public_chat", "trusted_private_chat"]
                 description: |-
                   Convenience parameter for setting various default state events
-                  based on a preset. Must be either:
-
-                  ``private_chat`` =>
-                    ``join_rules`` is set to ``invite``.
-                    ``history_visibility`` is set to ``shared``.
-
-                  ``trusted_private_chat`` =>
-                      ``join_rules`` is set to ``invite``.
-                      ``history_visibility`` is set to ``shared``.
-                      All invitees are given the same power level as the room creator.
-
-                  ``public_chat``: =>
-                      ``join_rules`` is set to ``public``.
-                      ``history_visibility`` is set to ``shared``.
+                  based on a preset.
               is_direct:
                 type: boolean
                 description: |-

api/server-server/directory.yaml

@@ -1,4 +1,5 @@
 # Copyright 2017 Kamax.io
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +15,7 @@
 
 swagger: '2.0'
 info:
-  title: "Matrix Federation Query Directory API"
+  title: "Matrix Federation Query API"
   version: "1.0.0"
 host: localhost:8448
 schemes:

api/server-server/query_general.yaml

@@ -0,0 +1,44 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation Query API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/query/{queryType}":
+    get:
+      summary: Query for information
+      description: |-
+        Performs a single query request on the receiving homeserver. The query string
+        arguments are dependent on which type of query is being made. Known query types
+        are specified as their own endpoints as an extension to this definition.
+      operationId: queryInfo
+      parameters:
+        - in: path
+          name: queryType
+          type: string
+          description: The type of query to make
+          required: true
+          x-example: profile
+      responses:
+        200:
+          description: |-
+            The query response. The schema varies depending on the query being made.

specification/server_server_api.rst

@@ -801,16 +801,7 @@ Retrieves all of the transactions later than any version given by the "v"
 arguments.
 
 
-To make a query::
-
-  GET .../query/<query_type>
-    Query args: as specified by the individual query types
-    Response: JSON encoding of a response object
-
-Performs a single query request on the receiving homeserver. The Query Type
-part of the path specifies the kind of query being made, and its query
-arguments have a meaning specific to that kind of query. The response is a
-JSON-encoded object whose meaning also depends on the kind of query.
+{{query_general_ss_http_api}}
 
 
 To join a room::