Support rendering schema definitions in the spec

scripts/templating/matrix_templates/sections.py

@@ -189,3 +189,17 @@ class MatrixSections(Sections):
         template = self.env.get_template("apis.tmpl")
         apis = self.units.get("apis")
         return template.render(apis=apis)
+
+    def render_swagger_definition(self):
+        rendered = {}
+        template = self.env.get_template("schema-definition.tmpl")
+        subtitle_title_char = self.units.get("spec_targets")[
+            "relative_title_styles"
+        ]["subtitle"]
+        definitions = self.units.get("swagger_definitions")
+        for group, swagger_def in definitions.items():
+            rendered["definition_" + group] = template.render(
+                definition=swagger_def['definition'],
+                examples=swagger_def['examples'],
+                title_kind=subtitle_title_char)
+        return rendered

scripts/templating/matrix_templates/templates/schema-definition.tmpl

@@ -0,0 +1,21 @@
+{% import 'tables.tmpl' as tables -%}
+
+``{{definition.title}}`` Schema
+{{(11 + definition.title | length) * title_kind}}
+
+{% if 'description' in definition %}
+{{definition.description}}
+{% endif %}
+
+{% for table in definition.tables -%}
+{{"``"+table.title+"``" if table.title else "" }}
+{{ tables.paramtable(table.rows) }}
+{% endfor %}
+
+Example{% if examples | length > 1 %}s{% endif %}:
+
+{% for example in examples %}
+.. code:: json
+
+    {{example | jsonify(4, 4)}}
+{% endfor %}

scripts/templating/matrix_templates/units.py

@@ -43,6 +43,13 @@ HTTP_APIS = {
     os.path.join(matrix_doc_dir, "api/push-gateway"): "push",
     os.path.join(matrix_doc_dir, "api/server-server"): "ss",
 }
+SWAGGER_DEFINITIONS = {
+    os.path.join(matrix_doc_dir, "api/application-service/definitions"): "as",
+    os.path.join(matrix_doc_dir, "api/client-server/definitions"): "cs",
+    #os.path.join(matrix_doc_dir, "api/identity/definitions"): "is",
+    #os.path.join(matrix_doc_dir, "api/push-gateway/definitions"): "push",
+    os.path.join(matrix_doc_dir, "api/server-server/definitions"): "ss",
+}
 EVENT_EXAMPLES = os.path.join(matrix_doc_dir, "event-schemas/examples")
 EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema")
 CORE_EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema/core-event-schema")
@@ -654,6 +661,37 @@ class MatrixUnits(Units):
                     apis[group_name] = api
         return apis
 
+
+    def load_swagger_definitions(self):
+        defs = {}
+        for path, prefix in SWAGGER_DEFINITIONS.items():
+            for filename in os.listdir(path):
+                if not filename.endswith(".yaml"):
+                    continue
+                filepath = os.path.join(path, filename)
+                logger.info("Reading swagger definition: %s" % filepath)
+                with open(filepath, "r") as f:
+                    # strip .yaml
+                    group_name = filename[:-5].replace("-", "_")
+                    group_name = "%s_%s" % (prefix, group_name)
+                    definition = yaml.load(f.read(), OrderedLoader)
+                    definition = resolve_references(filepath, definition)
+                    if 'type' not in definition:
+                        continue
+                    try:
+                        example = get_example_for_schema(definition)
+                    except:
+                        pass  # do nothing - we don't care
+                    if 'title' not in definition:
+                        definition['title'] = "NO_TITLE"
+                    definition['tables'] = get_tables_for_schema(definition)
+                    defs[group_name] = {
+                        "definition": definition,
+                        "examples": [example] if example is not None else [],
+                    }
+        return defs
+
+
     def load_common_event_fields(self):
         """Parse the core event schema files