From 98a445890ced148d6b9dd54e631401d092d4e477 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 13:25:01 -0600 Subject: [PATCH 1/2] 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 | 7 +++++++ scripts/templating/matrix_templates/units.py | 16 ++++++++++++++++ specification/application_service_api.rst | 2 ++ specification/client_server_api.rst | 2 ++ specification/identity_service_api.rst | 2 ++ specification/push_gateway.rst | 2 ++ specification/server_server_api.rst | 2 ++ 7 files changed, 33 insertions(+) diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 4c07649dd..f4c015c7f 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/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") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 94b535b52..11a9d441b 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/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 `_. +""" + 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: diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 69d39d212..8af10df8b 100644 --- a/specification/application_service_api.rst +++ b/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 diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index b377cbb8d..070d9de96 100644 --- a/specification/client_server_api.rst +++ b/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 diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 81ff0ede7..86170bd80 100644 --- a/specification/identity_service_api.rst +++ b/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 diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index e46238875..a77d43db0 100644 --- a/specification/push_gateway.rst +++ b/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. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 3bbfa12cc..e059d5607 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -17,6 +17,8 @@ Federation API ============== +{{unstable_warning_block_SERVER_RELEASE_LABEL}} + .. WARNING:: This API is unstable and will change without warning or discussion while we work towards a r0 release (scheduled for August 2018). From ab00630ebc3c6aa73c2d7573e5e8a197e7bc6a28 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 09:49:24 -0600 Subject: [PATCH 2/2] Don't include a second unstable warning in the s2s spec for now --- specification/server_server_api.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index e059d5607..3bbfa12cc 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -17,8 +17,6 @@ Federation API ============== -{{unstable_warning_block_SERVER_RELEASE_LABEL}} - .. WARNING:: This API is unstable and will change without warning or discussion while we work towards a r0 release (scheduled for August 2018).