Replace presence API with new template.

api/client-server/v1/presence.yaml

@@ -22,8 +22,10 @@ paths:
     put:
       summary: Update this user's presence state.
       description: |-
-        This API sets the given user's presence state. You cannot set the presence
-        state of another user.
+        This API sets the given user's presence state. When setting the status,
+        the activity time is updated to reflect that activity; the client does
+        not need to specify the ``last_active_ago`` field. You cannot set the
+        presence state of another user.
       security:
         - accessToken: []
       parameters:

specification/10_client_server_api.rst

@@ -1179,49 +1179,11 @@ address
 
 Presence
 ~~~~~~~~
-The client API for presence is on the following set of REST calls.
-
-Fetching basic status::
-
-  GET $PREFIX/presence/<user_id>/status
-
-  Returned content: JSON object containing the following keys:
-    presence: "offline"|"unavailable"|"online"|"free_for_chat"
-    status_msg: (optional) string of freeform text
-    last_active_ago: miliseconds since the last activity by the user
-
-Setting basic status::
-
-  PUT $PREFIX/presence/<user_id>/status
-
-  Content: JSON object containing the following keys:
-    presence and status_msg: as above
-
-When setting the status, the activity time is updated to reflect that activity;
-the client does not need to specify the ``last_active_ago`` field.
-
-Fetching the presence list::
-
-  GET $PREFIX/presence/list
-
-  Returned content: JSON array containing objects; each object containing the
-    following keys:
-    user_id: observed user ID
-    presence: "offline"|"unavailable"|"online"|"free_for_chat"
-    status_msg: (optional) string of freeform text
-    last_active_ago: miliseconds since the last activity by the user
-
-Maintaining the presence list::
-
-  POST $PREFIX/presence/list
-
-  Content: JSON object containing either or both of the following keys:
-    invite: JSON array of strings giving user IDs to send invites to
-    drop: JSON array of strings giving user IDs to remove from the list
-
 .. TODO-spec
   - Define how users receive presence invites, and how they accept/decline them
 
+{{presence_http_api}}
+
 Profiles
 ~~~~~~~~
 

templating/matrix_templates/sections.py

@@ -38,11 +38,33 @@ class MatrixSections(Sections):
             ))
         return "\n\n".join(sections)
 
-    def _render_http_api_group(self, group, sortFn=sorted, title_kind="-"):
+    def _render_http_api_group(self, group, sortFnOrPathList=None, 
+                               title_kind="-"):
         template = self.env.get_template("http-api.tmpl")
         http_api = self.units.get("swagger_apis")[group]["__meta"]
         sections = []
-        for endpoint in sortFn(http_api["endpoints"]):
+        endpoints = []
+        if sortFnOrPathList:
+            if isinstance(sortFnOrPathList, list):
+                # list of substrings to sort by
+                sorted_endpoints = []
+                for path_substr in sortFnOrPathList:
+                    for e in http_api["endpoints"]:
+                        if path_substr in e["path"]:
+                            sorted_endpoints.append(e)  # could have multiple
+                # dump rest
+                rest = [
+                    e for e in http_api["endpoints"] if e not in sorted_endpoints
+                ]
+                endpoints = sorted_endpoints + rest
+            else:
+                # guess it's a func, call it.
+                endpoints = sortFnOrPathList(http_api["endpoints"])
+        else:
+            # sort alphabetically based on path
+            endpoints = sorted(http_api["endpoints"], key=lambda k: k["path"])
+
+        for endpoint in endpoints:
             sections.append(template.render(
                 endpoint=endpoint,
                 title_kind=title_kind
@@ -50,18 +72,10 @@ class MatrixSections(Sections):
         return "\n\n".join(sections)
 
     def render_profile_http_api(self):
-        def sortFn(endpoints):
-            ordering = ["displayname", "avatar_url"]
-            sorted_endpoints = []
-            for path_substr in ordering:
-                for e in endpoints:
-                    if path_substr in e["path"]:
-                        sorted_endpoints.append(e)  # could have multiple
-            # dump rest
-            rest = [ e for e in endpoints if e not in sorted_endpoints ]
-            return sorted_endpoints + rest
         return self._render_http_api_group(
-            "profile", sortFn=sortFn, title_kind="+"
+            "profile", 
+            sortFnOrPathList=["displayname", "avatar_url"],
+            title_kind="+"
         )
 
     def render_sync_http_api(self):
@@ -71,7 +85,7 @@ class MatrixSections(Sections):
 
     def render_presence_http_api(self):
         return self._render_http_api_group(
-            "presence"
+            "presence", title_kind="+"
         )
 
     def render_room_events(self):