From 6e0fe705004e4e50638f1059be167f572b893a22 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Wed, 29 Aug 2018 16:38:59 +0100 Subject: [PATCH] make spec tables prettier --- scripts/css/basic.css | 23 +++++++++++++++++++ .../templates/common-event-fields.tmpl | 3 +-- .../matrix_templates/templates/events.tmpl | 1 - .../matrix_templates/templates/http-api.tmpl | 8 +++---- .../matrix_templates/templates/msgtypes.tmpl | 9 ++++++-- .../templates/schema-definition.tmpl | 2 +- .../matrix_templates/templates/tables.tmpl | 18 +++++++++++---- 7 files changed, 49 insertions(+), 15 deletions(-) diff --git a/scripts/css/basic.css b/scripts/css/basic.css index 6411570ee..1b5a4b61f 100644 --- a/scripts/css/basic.css +++ b/scripts/css/basic.css @@ -318,6 +318,29 @@ table.citation td { border-bottom: none; } +table.colwidths-auto caption { + font-family: monospace; + font-size: x-large; + padding: 2px; +} + +table.colwidths-auto { + width:100%; + margin-top: 20px; +} + +table.colwidths-auto tr td:nth-child(1) { + width: 15%; +} + +table.colwidths-auto tr td:nth-child(2) { + width: 15%; +} + +table.colwidths-auto tr td:nth-child(3) { + width: 70%; +} + /* -- other body styles ----------------------------------------------------- */ ol.arabic { diff --git a/scripts/templating/matrix_templates/templates/common-event-fields.tmpl b/scripts/templating/matrix_templates/templates/common-event-fields.tmpl index 9d0ddac3d..b69fb79c4 100644 --- a/scripts/templating/matrix_templates/templates/common-event-fields.tmpl +++ b/scripts/templating/matrix_templates/templates/common-event-fields.tmpl @@ -6,8 +6,7 @@ {{common_event.desc}} {% for table in common_event.tables %} -{{"``"+table.title+"``" if table.title else "" }} -{{ tables.paramtable(table.rows, ["Key", "Type", "Description"]) }} +{{ tables.paramtable(table.rows, [(table.title or "") ~ " Key", "Type", "Description"]) }} {% endfor %} diff --git a/scripts/templating/matrix_templates/templates/events.tmpl b/scripts/templating/matrix_templates/templates/events.tmpl index ded33859a..e5ec899f2 100644 --- a/scripts/templating/matrix_templates/templates/events.tmpl +++ b/scripts/templating/matrix_templates/templates/events.tmpl @@ -12,7 +12,6 @@ {{event.desc}} {% for table in event.content_fields %} -{{"``"+table.title+"``" if table.title else "" }} {{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"]) }} diff --git a/scripts/templating/matrix_templates/templates/http-api.tmpl b/scripts/templating/matrix_templates/templates/http-api.tmpl index 461a0b58c..db70da42f 100644 --- a/scripts/templating/matrix_templates/templates/http-api.tmpl +++ b/scripts/templating/matrix_templates/templates/http-api.tmpl @@ -18,8 +18,8 @@ Request format: {{ tables.split_paramtable(endpoint.req_param_by_loc) }} {% if (endpoint.req_body_tables) %} {% for table in endpoint.req_body_tables -%} -{{"``"+table.title+"``" if table.title else "" }} -{{ tables.paramtable(table.rows) }} +{{ tables.paramtable(table.rows, [(table.title or "") ~ " Parameter", "Type", "Description"] ) }} + {% endfor -%} {% endif -%} @@ -37,9 +37,9 @@ Response headers: Response format: {% for table in endpoint.res_tables -%} -{{"``"+table.title+"``" if table.title else "" }} -{{ tables.paramtable(table.rows) }} +{{ tables.paramtable(table.rows, [(table.title or "") ~ " Parameter", "Type", "Description"] ) }} + {% endfor %} {% endif -%} diff --git a/scripts/templating/matrix_templates/templates/msgtypes.tmpl b/scripts/templating/matrix_templates/templates/msgtypes.tmpl index 87cf4a193..dfcf2e9da 100644 --- a/scripts/templating/matrix_templates/templates/msgtypes.tmpl +++ b/scripts/templating/matrix_templates/templates/msgtypes.tmpl @@ -4,9 +4,14 @@ {{(4 + event.msgtype | length) * title_kind}} {{event.desc | wrap(80)}} {% for table in event.content_fields -%} -{{"``"+table.title+"``" if table.title else "" }} -{{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"]) }} +{% if table.title -%} +{% set tabletitle = table.title -%} +{% else -%} +{% set tabletitle = "" -%} +{% endif -%} + +{{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"] ) }} {% endfor %} Example: diff --git a/scripts/templating/matrix_templates/templates/schema-definition.tmpl b/scripts/templating/matrix_templates/templates/schema-definition.tmpl index e2be12e8a..0c4be577d 100644 --- a/scripts/templating/matrix_templates/templates/schema-definition.tmpl +++ b/scripts/templating/matrix_templates/templates/schema-definition.tmpl @@ -8,7 +8,7 @@ {% endif %} {% for table in definition.tables -%} -{{"``"+table.title+"``" if table.title else "" }} +{{"``7777"+table.title+"``" if table.title else "" }} {{ tables.paramtable(table.rows) }} {% endfor %} diff --git a/scripts/templating/matrix_templates/templates/tables.tmpl b/scripts/templating/matrix_templates/templates/tables.tmpl index 6d6e4f8ef..13ac08c85 100644 --- a/scripts/templating/matrix_templates/templates/tables.tmpl +++ b/scripts/templating/matrix_templates/templates/tables.tmpl @@ -36,6 +36,14 @@ {% set fieldwidths = (([titlerow] + flatrows) | fieldwidths(rowkeys[0:-1], [10, 10])) + [50] -%} +{% set caption = titlerow['key'] | replace (' Key', '') | replace ('Parameter', '') -%} +{% if caption == 'Content' -%} +{% set caption = '' -%} +{% endif -%} + +{{".. table:: "}}{{ caption }} +{{" :widths: auto"}} +{{""}} {{ tableheader(fieldwidths) }} {{ tablerow(fieldwidths, titlerow, rowkeys) }} {{ tableheader(fieldwidths) }} @@ -59,7 +67,7 @@ # Write a table header row, for the given column widths #} {% macro tableheader(widths) -%} -{% for arg in widths -%} +{{" "}}{% for arg in widths -%} {{"="*arg}} {% endfor -%} {% endmacro %} @@ -71,7 +79,7 @@ # attributes of 'row' to look up for values to put in the columns. #} {% macro tablerow(widths, row, keys) -%} -{% for key in keys -%} +{{" "}}{% for key in keys -%} {% set value=row[key] -%} {% if not loop.last -%} {# the first few columns need space after them -#} @@ -81,7 +89,7 @@ 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) -}} + indent_block(widths[0:-1]|sum + loop.index0 + 2) -}} {% endif -%} {% endfor -%} {% endmacro %} @@ -93,10 +101,10 @@ # write a tablespan row. This is a single value which spans the entire table. #} {% macro tablespan(widths, value) -%} -{{value}} +{{" "}}{{value}} {# we write a trailing space to stop the separator being misinterpreted # as a header line. -#} -{{"-"*(widths|sum + widths|length -1)}} {% endmacro %} +{{" "}}{{"-"*(widths|sum + widths|length -1)}} {% endmacro %}