Merge pull request #1599 from matrix-org/benpa/spec-tables-prettier

Benpa/spec tables prettier

scripts/css/basic.css

@@ -318,6 +318,46 @@ table.citation td {
     border-bottom: none;
 }
 
+table.colwidths-auto caption {
+    font-family: 'Inconsolata', monospace;
+    font-weight: 800;
+    font-size: 120%;
+    padding: 5px;
+    text-align: left;
+    margin-bottom: 2px;
+}
+
+ol, li {
+    margin: 0px 0px 0px 30px !important;
+}
+
+p.httpheaders {
+    font-weight: 800;
+    font-size: 120%;
+    padding: 5px;
+    text-align: left;
+    margin-bottom: 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%;
+    font-family: 'Inconsolata', monospace;
+}
+
+table.colwidths-auto tr td:nth-child(3) {
+    width: 70%;
+}
+
+
 /* -- other body styles ----------------------------------------------------- */
 
 ol.arabic {

scripts/css/nature.css

@@ -273,6 +273,7 @@ table {
 
 td[colspan]:not([colspan="1"]) {
     background: #eeeeee;
+    text-transform: capitalize;
 }
 
 thead {

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, ["Key", "Type", "Description"], (table.title or "")) }}
 
 {% endfor %}

scripts/templating/matrix_templates/templates/events.tmpl

@@ -12,9 +12,8 @@
 {{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"]) }}
+{{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"], (table.title or "")) }}
 
 {% endfor %}
 Example{% if examples | length > 1 %}s{% endif %}:

scripts/templating/matrix_templates/templates/http-api.tmpl

@@ -13,13 +13,16 @@
 {{":Rate-limited: Yes." if endpoint.rate_limited else "" }}
 {{":Requires auth: Yes." if endpoint.requires_auth else "" }}
 
-Request format:
+.. class:: httpheaders
+  
+  Request format:
+  
 {% if (endpoint.req_param_by_loc | length) %}
 {{ 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, caption=(table.title or "")) }}
-{{ tables.paramtable(table.rows) }}
+
 {% endfor -%}
 {% endif -%}
 
@@ -28,30 +31,41 @@ Request format:
 {% endif %}
 
 {% if endpoint.res_headers is not none -%}
-Response headers:
+
+.. class:: httpheaders
+  
+  Response headers:
 
 {{ tables.paramtable(endpoint.res_headers.rows) }}
 {% endif -%}
 
 {% if endpoint.res_tables|length > 0 -%}
-Response format:
+
+.. class:: httpheaders
+  
+  Response format:
 
 {% for table in endpoint.res_tables -%}
-{{"``"+table.title+"``" if table.title else "" }}
 
-{{ tables.paramtable(table.rows) }}
+{{ tables.paramtable(table.rows, caption=(table.title or "")) }}
+
 
 {% endfor %}
 {% endif -%}
 
-Example request:
+.. class:: httpheaders
+  
+  Example request:
 
 .. code:: http
 
   {{endpoint.example.req | indent_block(2)}}
 
 {% if endpoint.responses|length > 0 -%}
-Response{{"s" if endpoint.responses|length > 1 else "" }}:
+
+.. class:: httpheaders
+  
+  Response{{"s" if endpoint.responses|length > 1 else "" }}:
 
 {% endif -%}
 
@@ -63,7 +77,9 @@ Response{{"s" if endpoint.responses|length > 1 else "" }}:
 
 {% if res["example"] -%}
 
-Example
+.. class:: httpheaders
+  
+  Example
 
 .. code:: json
 

scripts/templating/matrix_templates/templates/msgtypes.tmpl

@@ -4,9 +4,8 @@
 {{(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"]) }}
+{{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"], (table.title or "")) }}
 
 {% endfor %}
 Example:

scripts/templating/matrix_templates/templates/tables.tmpl

@@ -8,8 +8,8 @@
  #
  # 'rows' is the list of parameters. Each row should be a TypeTableRow.
  #}
-{% macro paramtable(rows, titles=["Parameter", "Type", "Description"]) -%}
+{% macro paramtable(rows, titles=["Parameter", "Type", "Description"], caption="") -%}
-{{ split_paramtable({None: rows}, titles) }}
+{{ split_paramtable({None: rows}, titles, caption) }}
 {% endmacro %}
 
 
@@ -21,7 +21,7 @@
  # written for that location. This is used by the standard 'paramtable' macro.
  #}
 {% macro split_paramtable(rows_by_loc,
-      titles=["Parameter", "Type", "Description"]) -%}
+      titles=["Parameter", "Type", "Description"], caption="") -%}
 
 {% set rowkeys = ['key', 'title', 'desc'] %}
 {% set titlerow = {'key': titles[0], 'title': titles[1], 'desc': titles[2]} %}
@@ -36,6 +36,9 @@
 {% set fieldwidths = (([titlerow] + flatrows) |
         fieldwidths(rowkeys[0:-1], [10, 10])) + [50] -%}
 
+{{".. table:: "}}{{ caption }}
+{{"  :widths: auto"}}
+{{""}}
 {{ tableheader(fieldwidths) }}
 {{ tablerow(fieldwidths, titlerow, rowkeys) }}
 {{ tableheader(fieldwidths) }}
@@ -59,7 +62,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 +74,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 +84,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 +96,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 %}