Merge pull request #1631 from turt2live/travis/general/unstable-warning

 Render a warning if the spec is unstable

scripts/templating/matrix_templates/sections.py

@@ -207,6 +207,13 @@ def render_apis(self):
         apis = self.units.get("apis")
         return template.render(apis=apis)
 
+    def render_unstable_warnings(self):
+        rendered = {}
+        blocks = self.units.get("unstable_warnings")
+        for var, text in blocks.items():
+            rendered["unstable_warning_block_" + var] = text
+        return rendered
+
     def render_swagger_definition(self):
         rendered = {}
         template = self.env.get_template("schema-definition.tmpl")

scripts/templating/matrix_templates/units.py

@@ -971,6 +971,22 @@ def load_changelogs(self):
 
         return changelogs
 
+    def load_unstable_warnings(self, substitutions):
+        warning = """
+.. WARNING::
+    You are viewing an unstable version of this specification. Unstable
+    specifications may change at any time without notice. To view the
+    current specification, please `click here <latest.html>`_.
+"""
+        warnings = {}
+        for var in substitutions.keys():
+            key = var[1:-1] # take off the surrounding %-signs
+            if substitutions.get(var, "unstable") == "unstable":
+                warnings[key] = warning
+            else:
+                warnings[key] = ""
+        return warnings
+
 
     def load_spec_targets(self):
         with open(TARGETS, "r") as f:

specification/application_service_api.rst

@@ -16,6 +16,8 @@
 Application Service API
 =======================
 
+{{unstable_warning_block_APPSERVICE_RELEASE_LABEL}}
+
 The Matrix client-server API and server-server APIs provide the means to
 implement a consistent self-contained federated messaging fabric. However, they
 provide limited means of implementing custom server-side behaviour in Matrix

specification/client_server_api.rst

@@ -15,6 +15,8 @@
 Client-Server API
 =================
 
+{{unstable_warning_block_CLIENT_RELEASE_LABEL}}
+
 The client-server API provides a simple lightweight API to let clients send
 messages, control rooms and synchronise conversation history. It is designed to
 support both lightweight clients which store no state and lazy-load data from

specification/identity_service_api.rst

@@ -18,6 +18,8 @@
 Identity Service API
 ====================
 
+{{unstable_warning_block_IDENTITY_RELEASE_LABEL}}
+
 The Matrix client-server and server-server APIs are largely expressed in Matrix
 user identifiers. From time to time, it is useful to refer to users by other
 ("third-party") identifiers, or "3pid"s, e.g. their email address or phone

specification/push_gateway.rst

@@ -16,6 +16,8 @@
 Push Gateway API
 ================
 
+{{unstable_warning_block_PUSH_GATEWAY_RELEASE_LABEL}}
+
 Clients may want to receive push notifications when events are received at
 the homeserver. This is managed by a distinct entity called the Push Gateway.