Add common event field descriptions and template.

event-schemas/schema/v1/core

@@ -11,11 +11,12 @@
           "description": "The globally unique event identifier."
         },
         "user_id": {
-          "type": "string"
+          "type": "string",
+          "description": "Contains the fully-qualified ID of the user who *sent* this event."
         },
         "content": {
           "type": "object",
-          "description": "The fields in this object will vary depending on the type of event."
+          "description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body."
         },
         "type": {
           "type": "string",
@@ -27,13 +28,14 @@
     "room_event": {
         "type": "object",
         "title": "Room Event",
-        "description": "The basic set of fields all room events must have.",
+        "description": "In addition to the Event fields, Room Events MUST have the following additional field.",
         "allOf":[{
             "$ref": "#/definitions/event"
         }],
         "properties": {
             "room_id": {
-                "type": "string"
+                "type": "string",
+                "description": "The ID of the room associated with this event."
             }
         },
         "required": ["room_id"]
@@ -41,18 +43,18 @@
     "state_event": {
         "type": "object",
         "title": "State Event",
-        "description": "The basic set of fields which define a room state event.",
+        "description": "In addition to the Room Event fields, State Events have the following additional fields.",
         "allOf":[{
             "$ref": "#/definitions/room_event"
         }],
         "properties": {
             "state_key": {
                 "type": "string",
-                "description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a 0-length string."
+                "description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a 0-length string. The presence of this key makes this event a State Event."
             },
             "prev_content": {
                 "type": "object",
-                "description": "The previous content if this event has overwritten another event."
+                "description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing."
             }
         },
         "required": ["state_key"]

templating/internal/sections.py

@@ -16,8 +16,25 @@ def _render_section_room_events(env, units):
         ))
     return "\n\n".join(sections)
 
+def _render_ce_type(env, units, type):
+    template = env.get_template("common-event-fields.tmpl")
+    ce_types = units.get("common-event-fields")
+    return template.render(common_event=ce_types[type])
+
+def _render_ce_fields(env, units):
+    return _render_ce_type(env, units, "event")
+
+def _render_cre_fields(env, units):
+    return _render_ce_type(env, units, "room_event")
+
+def _render_cse_fields(env, units):
+    return _render_ce_type(env, units, "state_event")
+
 SECTION_DICT = {
-    "room_events": _render_section_room_events
+    "room_events": _render_section_room_events,
+    "common_event_fields": _render_ce_fields,
+    "common_state_event_fields": _render_cse_fields,
+    "common_room_event_fields": _render_cre_fields
 }
 
 def load(env, units):

templating/internal/units.py

@@ -11,6 +11,28 @@ def prop(obj, path):
         val = val.get(key, {})
     return val
 
+def _load_common_event_fields():
+    path = "../event-schemas/schema/v1/core"
+    event_types = {}
+    with open(path, "r") as f:
+        core_json = json.loads(f.read())
+        for event_type in core_json["definitions"]:
+            event_info = core_json["definitions"][event_type]
+            table = {
+                "title": event_info["title"],
+                "desc": event_info["description"],
+                "rows": []
+            }
+            for prop in event_info["properties"]:
+                row = {
+                    "key": prop,
+                    "type": event_info["properties"][prop]["type"],
+                    "desc": event_info["properties"][prop].get("description","")
+                }
+                table["rows"].append(row)
+            event_types[event_type] = table
+    return event_types
+
 def _load_examples():
     path = "../event-schemas/examples/v1"
     examples = {}
@@ -152,7 +174,8 @@ def _load_schemas():
 
 UNIT_DICT = {
     "event-examples": _load_examples,
-    "event-schemas": _load_schemas
+    "event-schemas": _load_schemas,
+    "common-event-fields": _load_common_event_fields
 }
 
 def load():

templating/templates/common-event-fields.tmpl

@@ -0,0 +1,17 @@
+{{common_event.title}}
+{{(common_event.title | length) * '-'}}
+
+{{common_event.desc | wrap(80)}}
+
+================== ================= ===========================================
+   Key                  Type                 Description
+================== ================= ===========================================
+{% for row in common_event.rows -%}
+{# -#}
+{# Row type needs to prepend spaces to line up with the type column (19 ch) -#}
+{# Desc needs to prepend the required text (maybe) and prepend spaces too -#}
+{#      It also needs to then wrap inside the desc col (43 ch width) -#}
+{# -#}
+{{row.key}}{{row.type|indent(19-row.key|length)}}{{row.desc | indent(18 - (row.type|length)) |wrap(43) |indent_block(37)}}
+{% endfor -%}
+================== ================= ===========================================