Remove stuff from 20_events.rst and replace with {{room_events}}. Update gendoc to call build.py for template vars.

scripts/gendoc.py

@@ -90,6 +90,14 @@ def rst2html(i, o):
                 settings_overrides=stylesheets
             )
 
+def run_through_template(input):
+    null = open(os.devnull, 'w')
+    subprocess.check_output(
+        ['python', 'build.py', "-o", "../scripts/tmp", "../scripts/"+input],
+        stderr=null,
+        cwd="../templating",
+    )
+
 def prepare_env():
     try:
         os.makedirs("./gen")
@@ -101,12 +109,12 @@ def prepare_env():
         pass
     
 def cleanup_env():
-    #pass
     shutil.rmtree("./tmp")
 
 def main():
     prepare_env()
     glob_spec_to("tmp/full_spec.rst")
+    run_through_template("tmp/full_spec.rst")
     shutil.copy("../supporting-docs/howtos/client-server.rst", "tmp/howto.rst")
     set_git_version("tmp/full_spec.rst")
     set_git_version("tmp/howto.rst")

specification/20_events.rst

@@ -75,228 +75,7 @@ Room Events
 This specification outlines several standard event types, all of which are
 prefixed with ``m.``
 
-``m.room.name``
+{{room_events}}
-  Summary:
-    Set the human-readable name for the room.
-  Type:
-    State event
-  JSON format:
-    ``{ "name" : "string" }``
-  Example:
-    ``{ "name" : "My Room" }``
-  Description:
-    A room has an opaque room ID which is not human-friendly to read. A room
-    alias is human-friendly, but not all rooms have room aliases. The room name
-    is a human-friendly string designed to be displayed to the end-user. The
-    room name is not *unique*, as multiple rooms can have the same room name
-    set. The room name can also be set when creating a room using |createRoom|_
-    with the ``name`` key.
-
-``m.room.topic``
-  Summary:
-    Set a topic for the room.
-  Type:
-    State event
-  JSON format:
-    ``{ "topic" : "string" }``
-  Example:
-    ``{ "topic" : "Welcome to the real world." }``
-  Description:
-    A topic is a short message detailing what is currently being discussed in
-    the room.  It can also be used as a way to display extra information about
-    the room, which may not be suitable for the room name. The room topic can
-    also be set when creating a room using |createRoom|_ with the ``topic``
-    key.
-
-``m.room.member``
-  Summary:
-    The current membership state of a user in the room.
-  Type:
-    State event
-  JSON format:
-    ``{ "membership" : "enum[ invite|join|leave|ban ]" }``
-  Example:
-    ``{ "membership" : "join" }``
-  Description:
-    Adjusts the membership state for a user in a room. It is preferable to use
-    the membership APIs (``/rooms/<room id>/invite`` etc) when performing
-    membership actions rather than adjusting the state directly as there are a
-    restricted set of valid transformations. For example, user A cannot force
-    user B to join a room, and trying to force this state change directly will
-    fail. See the `Rooms`_ section for how to use the membership APIs.
-
-``m.room.create``
-  Summary:
-    The first event in the room.
-  Type:
-    State event
-  JSON format:
-    ``{ "creator": "string"}``
-  Example:
-    ``{ "creator": "@user:example.com" }``
-  Description:
-    This is the first event in a room and cannot be changed. It acts as the
-    root of all other events.
-
-``m.room.join_rules``
-  Summary:
-    Descripes how/if people are allowed to join.
-  Type:
-    State event
-  JSON format:
-    ``{ "join_rule": "enum [ public|knock|invite|private ]" }``
-  Example:
-    ``{ "join_rule": "public" }``
-  Description:
-    TODO-doc : Use docs/models/rooms.rst
-
-``m.room.power_levels``
-  Summary:
-    Defines the power levels of users in the room.
-  Type:
-    State event
-  JSON format:
-    ``{ "<user_id>": <int>, ..., "default": <int>}``
-  Example:
-    ``{ "@user:example.com": 5, "@user2:example.com": 10, "default": 0 }``
-  Description:
-    If a user is in the list, then they have the associated power level.
-    Otherwise they have the default level. If not ``default`` key is supplied,
-    it is assumed to be 0.
-
-``m.room.add_state_level``
-  Summary:
-    Defines the minimum power level a user needs to add state.
-  Type:
-    State event
-  JSON format:
-    ``{ "level": <int> }``
-  Example:
-    ``{ "level": 5 }``
-  Description:
-    To add a new piece of state to the room a user must have the given power
-    level. This does not apply to updating current state, which is goverened
-    by the ``required_power_level`` event key.
-
-``m.room.send_event_level``
-  Summary:
-    Defines the minimum power level a user needs to send an event.
-  Type:
-    State event
-  JSON format:
-    ``{ "level": <int> }``
-  Example:
-    ``{ "level": 0 }``
-  Description:
-    To send a new event into the room a user must have at least this power
-    level. This allows ops to make the room read only by increasing this level,
-    or muting individual users by lowering their power level below this
-    threshold.
-
-``m.room.ops_levels``
-  Summary:
-    Defines the minimum power levels that a user must have before they can
-    kick and/or ban other users.
-  Type:
-    State event
-  JSON format:
-    ``{ "ban_level": <int>, "kick_level": <int>, "redact_level": <int> }``
-  Example:
-    ``{ "ban_level": 5, "kick_level": 5 }``
-  Description:
-    This defines who can ban and/or kick people in the room. Most of the time
-    ``ban_level`` will be greater than or equal to ``kick_level`` since
-    banning is more severe than kicking.
-
-``m.room.aliases``
-  Summary:
-    These state events are used to inform the room about what room aliases it
-    has.
-  Type:
-    State event
-  JSON format:
-    ``{ "aliases": ["string", ...] }``
-  Example:
-    ``{ "aliases": ["#foo:example.com"] }``
-  Description:
-    This event is sent by a homeserver directly to inform of changes to the
-    list of aliases it knows about for that room. As a special-case, the
-    ``state_key`` of the event is the homeserver which owns the room alias.
-    For example, an event might look like::
-
-      {
-        "type": "m.room.aliases",
-        "event_id": "012345678ab",
-        "room_id": "!xAbCdEfG:example.com",
-        "state_key": "example.com",
-        "content": {
-          "aliases": ["#foo:example.com"]
-        }
-      }
-
-    The event contains the full list of aliases now stored by the home server
-    that emitted it; additions or deletions are not explicitly mentioned as
-    being such. The entire set of known aliases for the room is then the union
-    of the individual lists declared by all such keys, one from each home
-    server holding at least one alias.
-
-    Clients `should` check the validity of any room alias given in this list
-    before presenting it to the user as trusted fact. The lists given by this
-    event should be considered simply as advice on which aliases might exist,
-    for which the client can perform the lookup to confirm whether it receives
-    the correct room ID.
-
-``m.room.message``
-  Summary:
-    A message.
-  Type:
-    Message event
-  JSON format:
-    ``{ "msgtype": "string" }``
-  Example:
-    ``{ "msgtype": "m.text", "body": "Testing" }``
-  Description:
-    This event is used when sending messages in a room. Messages are not
-    limited to be text.  The ``msgtype`` key outlines the type of message, e.g.
-    text, audio, image, video, etc.  Whilst not required, the ``body`` key
-    SHOULD be used with every kind of ``msgtype`` as a fallback mechanism when
-    a client cannot render the message. For more information on the types of
-    messages which can be sent, see `m.room.message msgtypes`_.
-
-``m.room.message.feedback``
-  Summary:
-    A receipt for a message.
-    N.B. not implemented in Synapse, and superceded in v2 CS API by the 'relates_to' event field.
-  Type:
-    Message event
-  JSON format:
-    ``{ "type": "enum [ delivered|read ]", "target_event_id": "string" }``
-  Example:
-    ``{ "type": "delivered", "target_event_id": "e3b2icys" }``
-  Description:
-    Feedback events are events sent to acknowledge a message in some way. There
-    are two supported acknowledgements: ``delivered`` (sent when the event has
-    been received) and ``read`` (sent when the event has been observed by the
-    end-user). The ``target_event_id`` should reference the ``m.room.message``
-    event being acknowledged.
-
-``m.room.redaction``
-  Summary:
-    Indicates a previous event has been redacted.
-  Type:
-    Message event
-  JSON format:
-    ``{ "reason": "string" }``
-  Description:
-    Events can be redacted by either room or server admins. Redacting an event
-    means that all keys not required by the protocol are stripped off, allowing
-    admins to remove offensive or illegal content that may have been attached
-    to any event. This cannot be undone, allowing server owners to physically
-    delete the offending data.  There is also a concept of a moderator hiding a
-    message event, which can be undone, but cannot be applied to state
-    events.
-    The event that has been redacted is specified in the ``redacts`` event
-    level key.
 
 m.room.message msgtypes
 ~~~~~~~~~~~~~~~~~~~~~~~

templating/build.py

@@ -114,7 +114,9 @@ def main(file_stream=None, out_dir=None):
     temp = Template(file_stream.read())
     print "Creating output for: %s" % file_stream.name
     output = create_from_template(temp, sections)
-    with open(os.path.join(out_dir, file_stream.name), "w") as f:
+    with open(
+            os.path.join(out_dir, os.path.basename(file_stream.name)), "w"
+            ) as f:
         f.write(output)
     print "Output file for: %s" % file_stream.name
 

templating/internal/units.py

@@ -19,7 +19,7 @@ def _load_examples():
             continue
         with open(os.path.join(path, filename), "r") as f:
             examples[filename] = json.loads(f.read())
-            if filename == "m.room.message_m.text":
+            if filename == "m.room.message#m.text":
                 examples["m.room.message"] = examples[filename]
     return examples