wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
Kegan Dougal 2015-05-20 15:40:06 +01:00
parent 66bbc30893
commit 02c44a889e
4 changed files with 14 additions and 225 deletions
Download patch file Download diff file Expand all files Collapse all files

10
scripts/gendoc.py
View file

@ -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")

223
specification/20_events.rst
View file

@ -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/<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.
{{room_events}}
m.room.message msgtypes
~~~~~~~~~~~~~~~~~~~~~~~

4
templating/build.py
View file

@ -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

2
templating/internal/units.py
View file

@ -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