Render a warning if the spec is unstable

Fixes https://github.com/matrix-org/matrix-doc/issues/1499

This is done by using magic variables in the RST. The magic variables are generated based on the substitutions available, making them available for use at build-time. 

Magic variables were chosen because it allows people to continue working on the spec and release process without having to worry about removing a chunk of text from the top of the file. Originally, this was attempted by using jinja2 if-statements, however the substitutions are replaced *after* the template is executed, so the condition would never match. 

The format of the variable is to make the templating happy. Using colons or percent signs results in the templator thinking something else is going on, and then complaining about format.

scripts/templating/matrix_templates/sections.py

@@ -207,6 +207,13 @@ class MatrixSections(Sections):
         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 @@ class MatrixUnits(Units):
 
         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: