Merge pull request #317 from ruma/master

Improvements to the spec index page

specification/index.rst

@@ -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
+Matrix is a set of APIs for open-federated Instant Messaging (IM), Voice
-https://github.com/matrix-org/matrix-doc using
+over IP (VoIP) and Internet of Things (IoT) communication, designed to create
-https://github.com/matrix-org/matrix-doc/blob/master/scripts/gendoc.py as of
+and support a new global real-time communication ecosystem.
-revision ``{{git_version}}`` -
-https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}.
 
-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.
+{{apis}}
-- `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.
 
-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
+The specification for each API is versioned in the form ``rX.Y.Z``. Changes to
-we had can be found `here`__.
+``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
-.. __: https://matrix.org/docs/spec/legacy/
+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.
-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.

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,6 +40,9 @@ class Units(object):
             if not func_name.startswith("load_"):
                 continue
             unit_key = func_name[len("load_"):]
+            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(

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

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)
+

templating/matrix_templates/templates/apis.tmpl

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

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 <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 = {}