Merge pull request #162 from matrix-org/rav/refactor_tables

Rewrite the table templates

templating/build.py

@@ -93,6 +93,27 @@ def main(input_module, file_stream=None, out_dir=None, verbose=False):
 
         return '\n\n'.join(output_lines)
 
+    def fieldwidths(input, keys, defaults=[], default_width=15):
+        """
+        A template filter to help in the generation of tables.
+
+        Given a list of rows, returns a list giving the maximum length of the
+        values in each column.
+
+        :param list[dict[str, str]] input: a list of rows. Each row should be a
+           dict with the keys given in ``keys``.
+        :param list[str] keys: the keys corresponding to the table columns
+        :param list[int] defaults: for each column, the default column width.
+        :param int default_width: if ``defaults`` is shorter than ``keys``, this
+           will be used as a fallback
+        """
+        def colwidth(key, default):
+            return reduce(max, (len(row[key]) for row in input),
+                          default if default is not None else default_width)
+
+        results = map(colwidth, keys, defaults)
+        return results
+
     # make Jinja aware of the templates and filters
     env = Environment(
         loader=FileSystemLoader(in_mod.exports["templates"]),
@@ -102,6 +123,7 @@ def main(input_module, file_stream=None, out_dir=None, verbose=False):
     env.filters["indent"] = indent
     env.filters["indent_block"] = indent_block
     env.filters["wrap"] = wrap
+    env.filters["fieldwidths"] = fieldwidths
 
     # load up and parse the lowest single units possible: we don't know or care
     # which spec section will use it, we just need it there in memory for when

templating/matrix_templates/templates/common-event-fields.tmpl

@@ -1,17 +1,8 @@
+{% import 'tables.tmpl' as tables -%}
+
 {{common_event.title}} Fields
 {{(7 + common_event.title | length) * title_kind}}
 
 {{common_event.desc | wrap(80)}}
 
-================== ================= ===========================================
-   Key                  Type                 Description
-================== ================= ===========================================
-{% for row in common_event.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 | indent(18 - (row.type|length)) |wrap(43) |indent_block(37)}}
-{% endfor -%}
-================== ================= ===========================================
+{{ tables.paramtable(common_event.rows, ["Key", "Type", "Description"]) }}

templating/matrix_templates/templates/events.tmpl

@@ -1,3 +1,5 @@
+{% import 'tables.tmpl' as tables -%}
+
 ``{{event.type}}``
 {{(4 + event.type | length) * title_kind}}
 *{{event.typeof}}*
@@ -7,18 +9,7 @@
 {% for table in event.content_fields -%}
 {{"``"+table.title+"``" if table.title else "" }}
 
-======================= ================= ===========================================
-   {{table.title or "Content"}} Key                Type                 Description
-======================= ================= ===========================================
-{% 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(24-row.key|length)}}{{row.desc|wrap(43,row.req_str | indent(18 - (row.type|length))) |indent_block(42)}}
-{% endfor -%}
-======================= ================= ===========================================
+{{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"]) }}
 
 {% endfor %}
 Example:

templating/matrix_templates/templates/http-api.tmpl

@@ -1,3 +1,5 @@
+{% import 'tables.tmpl' as tables -%}
+
 ``{{endpoint.method}} {{endpoint.path}}``
 {{(5 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}}
 {% if "alias_for_path" in endpoint -%}
@@ -13,17 +15,7 @@
 
 Request format:
 {% if (endpoint.req_param_by_loc | length) %}
-=============================================================== ================= ===========================================
-                       Parameter                                 Value                        Description
-=============================================================== ================= ===========================================
-{% for loc in endpoint.req_param_by_loc -%}
-*{{loc}} parameters*
------------------------------------------------------------------------------------------------------------------------------ 
-{% for param in endpoint.req_param_by_loc[loc] -%}
-{{param.key}}{{param.type|indent(64-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(82)}}
-{% endfor -%}
-{% endfor -%}
-=============================================================== ================= ===========================================
+{{ tables.split_paramtable(endpoint.req_param_by_loc) }}
 {% else %}
 `No parameters`
 {% endif %}
@@ -34,18 +26,7 @@ Response format:
 {% for table in endpoint.res_tables -%}
 {{"``"+table.title+"``" if table.title else "" }}
 
-======================= ========================= ==========================================
-      Param                        Type                           Description
-======================= ========================= ==========================================
-{% for row in table.rows -%}
-{# -#}
-{# Row type needs to prepend spaces to line up with the type column (20 ch) -#}
-{# Desc needs to prepend the required text (maybe) and prepend spaces too -#}
-{#      It also needs to then wrap inside the desc col (42 ch width) -#}
-{# -#}
-{{row.key}}{{row.type|indent(24-row.key|length)}}{{row.desc|wrap(42,row.req_str | indent(26 - (row.type|length))) |indent_block(50)}}
-{% endfor -%}
-======================= ========================= ==========================================
+{{ tables.paramtable(table.rows) }}
 
 {% endfor %}
 {% endif -%}

templating/matrix_templates/templates/msgtypes.tmpl

@@ -1,21 +1,12 @@
+{% import 'tables.tmpl' as tables -%}
+
 ``{{event.msgtype}}``
 {{(4 + event.msgtype | length) * title_kind}}
 {{event.desc | wrap(80)}}
 {% for table in event.content_fields -%}
 {{"``"+table.title+"``" if table.title else "" }}
 
-================== ================= ===========================================
-   {{table.title or "Content"}} Key          Type                 Description
-================== ================= ===========================================
-{% 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 -%}
-================== ================= ===========================================
+{{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"]) }}
 
 {% endfor %}
 Example:

templating/matrix_templates/templates/tables.tmpl

@@ -0,0 +1,104 @@
+{#
+ # A set of macros for generating RST tables
+ #}
+
+
+{#
+ # write a table for a list of parameters.
+ #
+ # 'rows' is the list of parameters. Each row should have the keys
+ # 'key', 'type', and 'desc'.
+ #}
+{% macro paramtable(rows, titles=["Parameter", "Type", "Description"]) -%}
+{{ split_paramtable({None: rows}, titles) }}
+{% endmacro %}
+
+
+{#
+ # write a table for the request parameters, split by location.
+ # 'rows_by_loc' is a map from location to a list of parameters.
+ #
+ # As a special case, if a key of 'rows_by_loc' is 'None', no title row is
+ # written for that location. This is used by the standard 'paramtable' macro.
+ #}
+{% macro split_paramtable(rows_by_loc, 
+      titles=["Parameter", "Type", "Description"]) -%}
+
+{% set rowkeys = ['key', 'type', 'desc'] %}
+{% set titlerow = {'key': titles[0], 'type': titles[1], 'desc': titles[2]} %}
+
+{# We need the rows flattened into a single list. Abuse the 'sum' filter to
+ # join arrays instead of add numbers. -#}
+{% set flatrows = rows_by_loc.values()|sum(start=[]) -%}
+
+{# Figure out the widths of the columns. The last column is always 50 characters
+ # wide; the others default to 10, but stretch if there is wider text in the
+ # column. -#}
+{% set fieldwidths = (([titlerow] + flatrows) | 
+        fieldwidths(rowkeys[0:-1], [10, 10])) + [50] -%}
+
+{{ tableheader(fieldwidths) }}
+{{ tablerow(fieldwidths, titlerow, rowkeys) }}
+{{ tableheader(fieldwidths) }}
+{% for loc in rows_by_loc -%}
+
+{% if loc != None -%}
+{{ tablespan(fieldwidths, "*" ~ loc ~ " parameters*") }}
+{% endif -%}
+
+{% for row in rows_by_loc[loc] -%}
+{{ tablerow(fieldwidths, row, rowkeys) }}
+{% endfor -%}
+{% endfor -%}
+
+{{ tableheader(fieldwidths) }}
+{% endmacro %}
+
+
+
+{#
+ # Write a table header row, for the given column widths 
+ #}
+{% macro tableheader(widths) -%}
+{% for arg in widths -%}
+{{"="*arg}} {% endfor -%}
+{% endmacro %}
+
+
+
+{#
+ # Write a normal table row. Each of 'widths' and 'keys' should be sequences 
+ # of the same length; 'widths' defines the column widths, and 'keys' the
+ # attributes of 'row' to look up for values to put in the columns.
+ #}
+{% macro tablerow(widths, row, keys) -%}
+{% for key in keys -%}
+{% set value=row[key] -%}
+{% if not loop.last -%}
+   {# the first few columns need space after them -#}
+   {{ value }}{{" "*(1+widths[loop.index0]-value|length) -}}
+{% else -%}
+   {# the last column needs wrapping and indenting (by the sum of the widths of
+   the preceding columns, plus the number of preceding columns (for the
+   separators)) -#}
+   {{ value | wrap(widths[loop.index0]) | 
+         indent_block(widths[0:-1]|sum + loop.index0) -}}
+{% endif -%}
+{% endfor -%}
+{% endmacro %}
+
+
+
+
+{# 
+ # write a tablespan row. This is a single value which spans the entire table.
+ #}
+{% macro tablespan(widths, value) -%}
+{{value}}
+{# we write a trailing space to stop the separator being misinterpreted
+ # as a header line. -#}
+{{"-"*(widths|sum + widths|length -1)}} {% endmacro %}
+
+
+
+