Add {{presence_events}}. Factor out common code in MatrixSections.

specification/20_events.rst

@@ -38,38 +38,14 @@ outlined below.
 Presence Events
 ~~~~~~~~~~~~~~~
 
-``m.presence``
-  Summary:
-    Informs you of a user's presence state changes.
-    
-  Type:
-    Presence event
-    
-  JSON format::
-  
-    { 
-      "displayname": "utf-8 string",
-      "avatar_url": "url",
-      "presence": "enum [ online|unavailable|offline|free_for_chat|hidden ]",
-      "last_active_ago": "milliseconds"
-    }
-    
-  Example::
-  
-    {
-      "displayname": "Matthew",
-      "avatar_url": "mxc://domain/id",
-      "presence": "online",
-      "last_active_ago": 10000
-    }
-    
-  Description:
-    Each user has the concept of presence information. This encodes the
-    "availability" of that user, suitable for display on other user's clients.
-    This is transmitted as an ``m.presence`` event and is one of the few events
-    which are sent *outside the context of a room*. The basic piece of presence
-    information is represented by the ``presence`` key, which is an enum of one
-    of the following:
+{{presence_events}}
+ 
+Each user has the concept of presence information. This encodes the
+"availability" of that user, suitable for display on other user's clients.
+This is transmitted as an ``m.presence`` event and is one of the few events
+which are sent *outside the context of a room*. The basic piece of presence
+information is represented by the ``presence`` key, which is an enum of one
+of the following:
 
       - ``online`` : The default state when the user is connected to an event
         stream.
@@ -81,14 +57,14 @@ Presence Events
         state anyway and generally interact with client features. (Not yet
         implemented in synapse).
 
-    In addition, the server maintains a timestamp of the last time it saw a
-    pro-active event from the user; either sending a message to a room, or
-    changing presence state from a lower to a higher level of availability
-    (thus: changing state from ``unavailable`` to ``online`` counts as a
-    proactive event, whereas in the other direction it will not). This timestamp
-    is presented via a key called ``last_active_ago``, which gives the relative
-    number of milliseconds since the message is generated/emitted that the user
-    was last seen active.
+In addition, the server maintains a timestamp of the last time it saw a
+pro-active event from the user; either sending a message to a room, or
+changing presence state from a lower to a higher level of availability
+(thus: changing state from ``unavailable`` to ``online`` counts as a
+proactive event, whereas in the other direction it will not). This timestamp
+is presented via a key called ``last_active_ago``, which gives the relative
+number of milliseconds since the message is generated/emitted that the user
+was last seen active.
     
 
 Events on Change of Profile Information

templating/matrix_templates/sections.py

@@ -14,7 +14,7 @@ class MatrixSections(Sections):
     def render_spec_version(self):
         return "0.1.0"
 
-    def _render_events(self, filterFn, sortFn):
+    def _render_events(self, filterFn, sortFn, title_kind="~"):
         template = self.env.get_template("events.tmpl")
         examples = self.units.get("event_examples")
         schemas = self.units.get("event_schemas")
@@ -24,24 +24,18 @@ class MatrixSections(Sections):
                 continue
             sections.append(template.render(
                 example=examples[event_name], 
-                event=schemas[event_name]
+                event=schemas[event_name],
+                title_kind=title_kind
             ))
         return "\n\n".join(sections)
 
     def render_room_events(self):
-        template = self.env.get_template("events.tmpl")
-        examples = self.units.get("event_examples")
-        schemas = self.units.get("event_schemas")
-        sections = []
-        for event_name in sorted(schemas):
-            if (not event_name.startswith("m.room") or 
-                    event_name.startswith("m.room.message#m.")):
-                continue
-            sections.append(template.render(
-                example=examples[event_name], 
-                event=schemas[event_name]
-            ))
-        return "\n\n".join(sections)
+        def filterFn(eventType):
+            return (
+                eventType.startswith("m.room") and 
+                not eventType.startswith("m.room.message#m.")
+            )
+        return self._render_events(filterFn, sorted)
 
     def render_msgtype_events(self):
         template = self.env.get_template("msgtypes.tmpl")
@@ -67,23 +61,14 @@ class MatrixSections(Sections):
         return "\n\n".join(sections)
 
     def render_voip_events(self):
-        template = self.env.get_template("events.tmpl")
-        examples = self.units.get("event_examples")
-        schemas = self.units.get("event_schemas")
-        sections = []
-        for event_name in sorted(schemas):
-            if not event_name.startswith("m.call"):
-                continue
-            sections.append(template.render(
-                example=examples[event_name], 
-                event=schemas[event_name]
-            ))
-        return "\n\n".join(sections)
+        def filterFn(eventType):
+            return eventType.startswith("m.call")
+        return self._render_events(filterFn, sorted)
 
     def render_presence_events(self):
         def filterFn(eventType):
             return eventType.startswith("m.presence")
-        return self._render_events(filterFn, sorted)
+        return self._render_events(filterFn, sorted, title_kind="+")
 
     def _render_ce_type(self, type):
         template = self.env.get_template("common-event-fields.tmpl")

templating/matrix_templates/templates/events.tmpl

@@ -1,5 +1,5 @@
 ``{{event.type}}``
-{{(4 + event.type | length) * '~'}}
+{{(4 + event.type | length) * title_kind}}
 *{{event.typeof}}*
   {{event.typeof_info}}