From 4b27d6a7a4d981174ec1e93a24a8b4ab4a3ade0f Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Fri, 22 Apr 2016 15:43:21 -0700 Subject: [PATCH 1/4] Reorganize spec index. --- specification/index.rst | 58 ++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/specification/index.rst b/specification/index.rst index 9c3897d1..8cfd3351 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -6,45 +6,43 @@ 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 `_. +For a more complete introduction to Matrix, see `Introduction `_. + +Matrix APIs +----------- The following APIs are documented in this specification: -- `Client-Server API `_ version %CLIENT_RELEASE_LABEL% for writing Matrix clients. -- `Server-Server API `_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix. -- `Application Service API `_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers. -- `Identity Service API `_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs. -- `Push Gateway API `_ version unstable for implementing a server that receives notifications about Matrix events a user is interested in. +- `Client-Server API `_ (%CLIENT_RELEASE_LABEL%) Interaction between clients and servers +- `Server-Server API `_ (%SERVER_RELEASE_LABEL%) Federation between servers +- `Application Service API `_ (%CLIENT_RELEASE_LABEL%) Privileged server plugins +- `Identity Service API `_ (unstable) Mapping of third party IDs with Matrix IDs +- `Push Gateway API `_ (unstable) Push notifications for Matrix events -There are also some `appendices `_. +`Appendices `_ with supplemental information not specific to +of the above APIs is also available. -Any developments since the latest release can be found `here`__. +Specification Version +--------------------- -.. __: https://matrix.org/speculator/spec/head/ +The documents in the specification are generated from +`matrix-doc `_ as of Git commit +`{{git_version}} `_. -Old releases of the spec: +The following other versions of the specification are also available, +in reverse chronological order: +- `HEAD `_: Includes all changes since the latest versioned release. - `r0.0.1 `_ - `r0.0.0 `_ +- `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. From 5b18db9096bf0d1c3ac5a1f778bb0a53cbee6971 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Tue, 26 Apr 2016 10:23:36 -0400 Subject: [PATCH 2/4] Make list of APIs on the index a table. --- specification/index.rst | 8 ++---- templating/batesian/units.py | 12 +++++++-- templating/build.py | 5 +++- templating/matrix_templates/sections.py | 5 ++++ .../matrix_templates/templates/apis.tmpl | 4 +++ templating/matrix_templates/units.py | 25 +++++++++++++++++++ 6 files changed, 50 insertions(+), 9 deletions(-) create mode 100644 templating/matrix_templates/templates/apis.tmpl diff --git a/specification/index.rst b/specification/index.rst index 8cfd3351..4d422370 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -17,14 +17,10 @@ Matrix APIs The following APIs are documented in this specification: -- `Client-Server API `_ (%CLIENT_RELEASE_LABEL%) Interaction between clients and servers -- `Server-Server API `_ (%SERVER_RELEASE_LABEL%) Federation between servers -- `Application Service API `_ (%CLIENT_RELEASE_LABEL%) Privileged server plugins -- `Identity Service API `_ (unstable) Mapping of third party IDs with Matrix IDs -- `Push Gateway API `_ (unstable) Push notifications for Matrix events +{{apis}} `Appendices `_ with supplemental information not specific to -of the above APIs is also available. +one of the above APIs is also available. Specification Version --------------------- diff --git a/templating/batesian/units.py b/templating/batesian/units.py index 144cf245..0b665b17 100644 --- a/templating/batesian/units.py +++ b/templating/batesian/units.py @@ -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","" diff --git a/templating/build.py b/templating/build.py index 4787b7b1..5c74d467 100755 --- a/templating/build.py +++ b/templating/build.py @@ -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 diff --git a/templating/matrix_templates/sections.py b/templating/matrix_templates/sections.py index 2db10a2f..f43a567a 100644 --- a/templating/matrix_templates/sections.py +++ b/templating/matrix_templates/sections.py @@ -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) + diff --git a/templating/matrix_templates/templates/apis.tmpl b/templating/matrix_templates/templates/apis.tmpl new file mode 100644 index 00000000..943aadc8 --- /dev/null +++ b/templating/matrix_templates/templates/apis.tmpl @@ -0,0 +1,4 @@ +{% import 'tables.tmpl' as tables -%} + +{{ tables.paramtable(apis.rows, ["API", "Version", "Description"]) }} + diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 3064ba7d..c8716bdf 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -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 `_", + "type": substitutions["%CLIENT_RELEASE_LABEL%"], + "desc": "Interaction between clients and servers", + }, { + "key": "`Server-Server API `_", + "type": substitutions["%SERVER_RELEASE_LABEL%"], + "desc": "Federation between servers", + }, { + "key": "`Application Service API `_", + "type": substitutions["%CLIENT_RELEASE_LABEL%"], + "desc": "Privileged server plugins", + }, { + "key": "`Identity Service API `_", + "type": "unstable", + "desc": "Mapping of third party IDs with Matrix ID", + }, { + "key": "`Push Gateway API `_", + "type": "unstable", + "desc": "Push notifications for Matrix events", + }] + } + def load_event_examples(self): path = EVENT_EXAMPLES examples = {} From 22b542e3f9184c4680dad61a00bb6683d5f7f455 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Wed, 4 May 2016 02:27:29 -0700 Subject: [PATCH 3/4] Fix grammar in spec index. --- specification/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/index.rst b/specification/index.rst index 4d422370..1cae9584 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -20,7 +20,7 @@ The following APIs are documented in this specification: {{apis}} `Appendices `_ with supplemental information not specific to -one of the above APIs is also available. +one of the above APIs are also available. Specification Version --------------------- From c44d61b3a97899ca074c0f0692068d18d68db57d Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Wed, 4 May 2016 02:30:44 -0700 Subject: [PATCH 4/4] Clarify which documents are generated from scripts. --- specification/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/index.rst b/specification/index.rst index 1cae9584..e9644ddf 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -25,7 +25,7 @@ one of the above APIs are also available. Specification Version --------------------- -The documents in the specification are generated from +The documents in this version of the specification are generated from `matrix-doc `_ as of Git commit `{{git_version}} `_.