Rewrite the table templates

Allow columns to stretch if they end up with wide content.

Apart from the hassle of having to manually update the calculations, having the
columns wide enough to hold the widest thing they might ever have leads to
tables with lots of whitespace in the results.

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(44-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(62)}}
-{% 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 %}
+
+
+
+