Merge pull request #317 from ruma/master

Improvements to the spec index page
pull/977/head
Richard van der Hoff 9 years ago
commit 4c46c95d0e

@ -6,45 +6,39 @@ Matrix Specification
.. have should hopefully not get complex enough that we need to worry about
.. versioning it.
This specification has been generated from
https://github.com/matrix-org/matrix-doc using
https://github.com/matrix-org/matrix-doc/blob/master/scripts/gendoc.py as of
revision ``{{git_version}}`` -
https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}.
Matrix is a set of APIs for open-federated Instant Messaging (IM), Voice
over IP (VoIP) and Internet of Things (IoT) communication, designed to create
and support a new global real-time communication ecosystem.
There is an `introduction and overview to the specification here <intro.html>`_.
For a more complete introduction to Matrix, see `Introduction <intro.html>`_.
Matrix APIs
-----------
The following APIs are documented in this specification:
- `Client-Server API <client_server.html>`_ version %CLIENT_RELEASE_LABEL% for writing Matrix clients.
- `Server-Server API <server_server.html>`_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix.
- `Application Service API <application_service.html>`_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers.
- `Identity Service API <identity_service.html>`_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs.
- `Push Gateway API <push_gateway.html>`_ version unstable for implementing a server that receives notifications about Matrix events a user is interested in.
{{apis}}
There are also some `appendices <appendices.html>`_.
`Appendices <appendices.html>`_ with supplemental information not specific to
one of the above APIs are also available.
Any developments since the latest release can be found `here`__.
Specification Version
---------------------
.. __: https://matrix.org/speculator/spec/head/
The documents in this version of the specification are generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
Old releases of the spec:
The following other versions of the specification are also available,
in reverse chronological order:
- `HEAD <https://matrix.org/speculator/spec/head/>`_: Includes all changes since the latest versioned release.
- `r0.0.1 <https://matrix.org/docs/spec/r0.0.1>`_
- `r0.0.0 <https://matrix.org/docs/spec/r0.0.0>`_
- `Legacy <https://matrix.org/docs/spec/legacy/>`_: The last draft before the spec was formally released in version r0.0.0.
Before we formally started releasing the specification, the last working copy
we had can be found `here`__.
.. __: https://matrix.org/docs/spec/legacy/
Versioning
----------
The specifications are each versioned in the form ``rX.Y.Z``.
Changes to ``X`` and ``Y`` should not be assumed to be compatible with any other version.
For a fixed ``X`` and ``Y``, any ``Z`` should be assumed to be compatible with any lesser ``Z``.
For example, it is safe to assume that a server which claims to implement ``r0.1.2`` supports ``r0.1.0``, but not vice-versa.
The specification for each API is versioned in the form ``rX.Y.Z``. Changes to
``X`` and ``Y`` should not be assumed to be compatible with any other version.
For a fixed ``X`` and ``Y``, any ``Z`` should be assumed to be compatible with
any lesser ``Z``. For example, it is safe to assume that a server which claims
to implement ``r0.1.2`` supports ``r0.1.0``, but not vice-versa.

@ -17,9 +17,14 @@ class Units(object):
return val
def __init__(self, debug=False):
def __init__(self, debug=False, substitutions=None):
self.debug = debug
if substitutions is None:
self.substitutions = {}
else:
self.substitutions = substitutions
def log(self, text):
if self.debug:
func_name = ""
@ -35,7 +40,10 @@ class Units(object):
if not func_name.startswith("load_"):
continue
unit_key = func_name[len("load_"):]
unit_dict[unit_key] = func()
if len(inspect.getargs(func.func_code).args) > 1:
unit_dict[unit_key] = func(self.substitutions)
else:
unit_dict[unit_key] = func()
self.log("Generated unit '%s' : %s" % (
unit_key, json.dumps(unit_dict[unit_key])[:50].replace(
"\n",""

@ -131,7 +131,10 @@ def main(input_module, files=None, out_dir=None, verbose=False, substitutions={}
# which spec section will use it, we just need it there in memory for when
# they want it.
units = AccessKeyStore(
existing_data=in_mod.exports["units"](debug=verbose).get_units()
existing_data=in_mod.exports["units"](
debug=verbose,
substitutions=substitutions,
).get_units()
)
# use the units to create RST sections

@ -176,3 +176,8 @@ class MatrixSections(Sections):
def render_common_state_event_fields(self):
return self._render_ce_type("state_event")
def render_apis(self):
template = self.env.get_template("apis.tmpl")
apis = self.units.get("apis")
return template.render(apis=apis)

@ -0,0 +1,4 @@
{% import 'tables.tmpl' as tables -%}
{{ tables.paramtable(apis.rows, ["API", "Version", "Description"]) }}

@ -536,6 +536,31 @@ class MatrixUnits(Units):
event_types[event_type] = table
return event_types
def load_apis(self, substitutions):
return {
"rows": [{
"key": "`Client-Server API <client_server.html>`_",
"type": substitutions["%CLIENT_RELEASE_LABEL%"],
"desc": "Interaction between clients and servers",
}, {
"key": "`Server-Server API <server_server.html>`_",
"type": substitutions["%SERVER_RELEASE_LABEL%"],
"desc": "Federation between servers",
}, {
"key": "`Application Service API <application_service.html>`_",
"type": substitutions["%CLIENT_RELEASE_LABEL%"],
"desc": "Privileged server plugins",
}, {
"key": "`Identity Service API <identity_service.html>`_",
"type": "unstable",
"desc": "Mapping of third party IDs with Matrix ID",
}, {
"key": "`Push Gateway API <push_gateway.html>`_",
"type": "unstable",
"desc": "Push notifications for Matrix events",
}]
}
def load_event_examples(self):
path = EVENT_EXAMPLES
examples = {}

Loading…
Cancel
Save