diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 92024035..02de6d86 100755 --- a/scripts/gendoc.py +++ b/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") diff --git a/specification/20_events.rst b/specification/20_events.rst index 532ff997..ada4980e 100644 --- a/specification/20_events.rst +++ b/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`` - 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//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: - ``{ "": , ..., "default": }`` - 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": }`` - 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": }`` - 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": , "kick_level": , "redact_level": }`` - 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. +{{room_events}} m.room.message msgtypes ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/templating/build.py b/templating/build.py index 40115370..6c398848 100755 --- a/templating/build.py +++ b/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 diff --git a/templating/internal/units.py b/templating/internal/units.py index a1b90ad4..99dcf3d0 100644 --- a/templating/internal/units.py +++ b/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