From 14d004146b754d80095cebe38596e7d1d00d9174 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Tue, 2 Jun 2015 12:03:10 +0100
Subject: [PATCH] Implement nested tables for HTTP APIs. It even works(!)

---
 templating/batesian/sections.py               |  7 ++++---
 .../matrix_templates/templates/http-api.tmpl  | 20 ++++++++++++++-----
 templating/matrix_templates/units.py          | 19 ++++++++++--------
 3 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/templating/batesian/sections.py b/templating/batesian/sections.py
index aa97662c..11c34fb3 100644
--- a/templating/batesian/sections.py
+++ b/templating/batesian/sections.py
@@ -25,13 +25,14 @@ class Sections(object):
             if not func_name.startswith("render_"):
                 continue
             section_key = func_name[len("render_"):]
+            self.log("Generating section '%s'" % section_key)
             section = func()
             if not isinstance(section, basestring):
                 raise Exception(
                     "Section function '%s' didn't return a string!" % func_name
                 )
             section_dict[section_key] = section
-            self.log("Generated section '%s' : %s" % (
-                section_key, section[:60].replace("\n","")
-            ))
+            self.log(
+                "  Generated. Snippet => %s" % section[:60].replace("\n","")
+            )
         return section_dict
\ No newline at end of file
diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl
index e9fb7322..5e80f168 100644
--- a/templating/matrix_templates/templates/http-api.tmpl
+++ b/templating/matrix_templates/templates/http-api.tmpl
@@ -20,17 +20,27 @@ Request format:
 {% endfor -%}
 ================== ================= ===========================================
 
-{% if endpoint.res_params|length > 0 -%}
+{% if endpoint.res_tables|length > 0 -%}
 Response format:
 
+{% for table in endpoint.res_tables -%}
+{{"``"+table.title+"``" if table.title else "" }}
+
 ================== ================= ===========================================
-   Parameter            Value                        Description
+      Param              Type                 Description
 ================== ================= ===========================================
-{% for param in endpoint.res_params -%}
-{{param.key}}{{param.type|indent(19-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(37)}}
+{% for row in table.rows -%}
+{# -#}
+{# Row type needs to prepend spaces to line up with the type column (19 ch) -#}
+{# Desc needs to prepend the required text (maybe) and prepend spaces too -#}
+{#      It also needs to then wrap inside the desc col (43 ch width) -#}
+{# -#}
+{{row.key}}{{row.type|indent(19-row.key|length)}}{{row.desc|wrap(43,row.req_str | indent(18 - (row.type|length))) |indent_block(37)}}
 {% endfor -%}
 ================== ================= ===========================================
-{% endif %}
+
+{% endfor %}
+{% endif -%}
 
 Example request::
 
diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py
index 41a62099..062f3e43 100644
--- a/templating/matrix_templates/units.py
+++ b/templating/matrix_templates/units.py
@@ -113,7 +113,7 @@ class MatrixUnits(Units):
                     "requires_auth": "security" in single_api,
                     "rate_limited": 429 in single_api.get("responses", {}),
                     "req_params": [],
-                    "res_params": [],
+                    "res_tables": [],
                     "example": {
                         "req": "",
                         "res": ""
@@ -219,16 +219,19 @@ class MatrixUnits(Units):
                 res_type = Units.prop(res, "schema/type")
                 if res_type and res_type not in ["object", "array"]:
                     # response is a raw string or something like that
-                    endpoint["res_params"].append({
-                        "key": res["schema"].get("name", ""),
-                        "type": res_type,
-                        "desc": res.get("description", "")
+                    endpoint["res_tables"].append({
+                        "title": None,
+                        "rows": [{
+                            "key": res["schema"].get("name", ""),
+                            "type": res_type,
+                            "desc": res.get("description", "")
+                        }]
                     })
                 elif res_type and Units.prop(res, "schema/properties"):  # object
                     res_tables = get_json_schema_object_fields(res["schema"])
-                    # TODO: Is this good enough or should we be doing multiple
-                    # tables for HTTP responses?!
-                    endpoint["res_params"] = res_tables[0]["rows"]
+                    for table in res_tables:
+                        if "no-table" not in table:
+                            endpoint["res_tables"].append(table)
 
                 endpoints.append(endpoint)