From 6e0fe705004e4e50638f1059be167f572b893a22 Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Wed, 29 Aug 2018 16:38:59 +0100
Subject: [PATCH 1/8] 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 6411570e..1b5a4b61 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 9d0ddac3..b69fb79c 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 ded33859..e5ec899f 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 461a0b58..db70da42 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 87cf4a19..dfcf2e9d 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 e2be12e8..0c4be577 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 6d6e4f8e..13ac08c8 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 %}
 
 
 

From 989b50a1a09e854f3cbe3dda62686e575205912e Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Wed, 29 Aug 2018 16:40:26 +0100
Subject: [PATCH 2/8] remove debug string

---
 .../matrix_templates/templates/schema-definition.tmpl           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/templating/matrix_templates/templates/schema-definition.tmpl b/scripts/templating/matrix_templates/templates/schema-definition.tmpl
index 0c4be577..e2be12e8 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 -%}
-{{"``7777"+table.title+"``" if table.title else "" }}
+{{"``"+table.title+"``" if table.title else "" }}
 {{ tables.paramtable(table.rows) }}
 {% endfor %}
 

From 380a53ecbababf086104443babcc5a87bd6100e1 Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Wed, 29 Aug 2018 17:18:37 +0100
Subject: [PATCH 3/8] adjust caption -> smaller, left align

---
 scripts/css/basic.css | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/css/basic.css b/scripts/css/basic.css
index 1b5a4b61..ca21a859 100644
--- a/scripts/css/basic.css
+++ b/scripts/css/basic.css
@@ -320,8 +320,9 @@ table.citation td {
 
 table.colwidths-auto caption {
     font-family: monospace;
-    font-size: x-large;
+    font-size: large;
     padding: 2px;
+    text-align: left;
 }
 
 table.colwidths-auto {

From 9e1d6d74901735a78b5725756521a52383028dd5 Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Thu, 30 Aug 2018 17:01:27 +0100
Subject: [PATCH 4/8] sanitise caption handling

---
 .../templates/common-event-fields.tmpl                |  2 +-
 .../templating/matrix_templates/templates/events.tmpl |  2 +-
 .../matrix_templates/templates/http-api.tmpl          |  4 ++--
 .../matrix_templates/templates/msgtypes.tmpl          |  8 +-------
 .../templating/matrix_templates/templates/tables.tmpl | 11 +++--------
 5 files changed, 8 insertions(+), 19 deletions(-)

diff --git a/scripts/templating/matrix_templates/templates/common-event-fields.tmpl b/scripts/templating/matrix_templates/templates/common-event-fields.tmpl
index b69fb79c..f62f59ba 100644
--- a/scripts/templating/matrix_templates/templates/common-event-fields.tmpl
+++ b/scripts/templating/matrix_templates/templates/common-event-fields.tmpl
@@ -7,6 +7,6 @@
 
 {% for table in common_event.tables %}
 
-{{ tables.paramtable(table.rows, [(table.title or "") ~ " Key", "Type", "Description"]) }}
+{{ tables.paramtable(table.rows, ["Key", "Type", "Description"], (table.title or "")) }}
 
 {% endfor %}
diff --git a/scripts/templating/matrix_templates/templates/events.tmpl b/scripts/templating/matrix_templates/templates/events.tmpl
index e5ec899f..679aee5b 100644
--- a/scripts/templating/matrix_templates/templates/events.tmpl
+++ b/scripts/templating/matrix_templates/templates/events.tmpl
@@ -13,7 +13,7 @@
 
 {% for table in event.content_fields %}
 
-{{ 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 %}:
diff --git a/scripts/templating/matrix_templates/templates/http-api.tmpl b/scripts/templating/matrix_templates/templates/http-api.tmpl
index db70da42..1d486cd3 100644
--- a/scripts/templating/matrix_templates/templates/http-api.tmpl
+++ b/scripts/templating/matrix_templates/templates/http-api.tmpl
@@ -18,7 +18,7 @@ Request format:
 {{ tables.split_paramtable(endpoint.req_param_by_loc) }}
 {% if (endpoint.req_body_tables) %}
 {% for table in endpoint.req_body_tables -%}
-{{ tables.paramtable(table.rows, [(table.title or "") ~ " Parameter", "Type", "Description"] ) }}
+{{ tables.paramtable(table.rows, caption=(table.title or "")) }}
 
 {% endfor -%}
 {% endif -%}
@@ -38,7 +38,7 @@ Response format:
 
 {% for table in endpoint.res_tables -%}
 
-{{ tables.paramtable(table.rows, [(table.title or "") ~ " Parameter", "Type", "Description"] ) }}
+{{ tables.paramtable(table.rows, caption=(table.title or "")) }}
 
 
 {% endfor %}
diff --git a/scripts/templating/matrix_templates/templates/msgtypes.tmpl b/scripts/templating/matrix_templates/templates/msgtypes.tmpl
index dfcf2e9d..060a7db0 100644
--- a/scripts/templating/matrix_templates/templates/msgtypes.tmpl
+++ b/scripts/templating/matrix_templates/templates/msgtypes.tmpl
@@ -5,13 +5,7 @@
 {{event.desc | wrap(80)}}
 {% for table in event.content_fields -%}
 
-{% if table.title -%}
-{% set tabletitle = table.title -%}
-{% else -%}
-{% set tabletitle = "" -%}
-{% endif -%}
-
-{{ 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:
diff --git a/scripts/templating/matrix_templates/templates/tables.tmpl b/scripts/templating/matrix_templates/templates/tables.tmpl
index 13ac08c8..fde546a7 100644
--- a/scripts/templating/matrix_templates/templates/tables.tmpl
+++ b/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"]) -%}
-{{ split_paramtable({None: rows}, titles) }}
+{% macro paramtable(rows, titles=["Parameter", "Type", "Description"], caption="") -%}
+{{ 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,11 +36,6 @@
 {% 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"}}
 {{""}}

From f1ae872857125589472521228ee9bff3a025f7f4 Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Thu, 30 Aug 2018 17:16:45 +0100
Subject: [PATCH 5/8] light zebra striping for tables

---
 scripts/css/basic.css | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/scripts/css/basic.css b/scripts/css/basic.css
index ca21a859..1b2e3526 100644
--- a/scripts/css/basic.css
+++ b/scripts/css/basic.css
@@ -342,6 +342,10 @@ table.colwidths-auto tr td:nth-child(3) {
     width: 70%;
 }
 
+table.colwidths-auto tr:nth-child(even) {
+    background-color: #f4f4f4;
+}
+
 /* -- other body styles ----------------------------------------------------- */
 
 ol.arabic {

From e8afab1fe51797e6a5dad4b9d7f4ccfe3159e0f7 Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Fri, 31 Aug 2018 13:55:27 +0100
Subject: [PATCH 6/8] many visual improvements

---
 scripts/css/basic.css                         | 24 ++++++++++++----
 .../matrix_templates/templates/http-api.tmpl  | 28 +++++++++++++++----
 2 files changed, 40 insertions(+), 12 deletions(-)

diff --git a/scripts/css/basic.css b/scripts/css/basic.css
index 1b2e3526..c26bb711 100644
--- a/scripts/css/basic.css
+++ b/scripts/css/basic.css
@@ -319,10 +319,24 @@ table.citation td {
 }
 
 table.colwidths-auto caption {
-    font-family: monospace;
-    font-size: large;
-    padding: 2px;
+    font-family: 'Inconsolata', monospace;
+    font-weight: 800;
+    font-size: 110%;
+    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 {
@@ -336,15 +350,13 @@ table.colwidths-auto tr td:nth-child(1) {
 
 table.colwidths-auto tr td:nth-child(2) {
     width: 15%;
+    font-family: 'Inconsolata', monospace;
 }
 
 table.colwidths-auto tr td:nth-child(3) {
     width: 70%;
 }
 
-table.colwidths-auto tr:nth-child(even) {
-    background-color: #f4f4f4;
-}
 
 /* -- other body styles ----------------------------------------------------- */
 
diff --git a/scripts/templating/matrix_templates/templates/http-api.tmpl b/scripts/templating/matrix_templates/templates/http-api.tmpl
index 1d486cd3..0b9207d9 100644
--- a/scripts/templating/matrix_templates/templates/http-api.tmpl
+++ b/scripts/templating/matrix_templates/templates/http-api.tmpl
@@ -13,7 +13,10 @@
 {{":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) %}
@@ -28,13 +31,19 @@ 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 -%}
 
@@ -44,14 +53,19 @@ Response format:
 {% 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
 

From 778fe2a47aa3a659bca4f985256cf9c2c98a107f Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Fri, 31 Aug 2018 14:29:46 +0100
Subject: [PATCH 7/8] css caption size tweak

---
 scripts/css/basic.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/css/basic.css b/scripts/css/basic.css
index c26bb711..1112cdfc 100644
--- a/scripts/css/basic.css
+++ b/scripts/css/basic.css
@@ -321,7 +321,7 @@ table.citation td {
 table.colwidths-auto caption {
     font-family: 'Inconsolata', monospace;
     font-weight: 800;
-    font-size: 110%;
+    font-size: 120%;
     padding: 5px;
     text-align: left;
     margin-bottom: 2px;

From c77b505441c2e088a00cf54efc16758b05601418 Mon Sep 17 00:00:00 2001
From: Ben Parsons <ben@bpulse.co.uk>
Date: Fri, 31 Aug 2018 14:37:47 +0100
Subject: [PATCH 8/8] capitali[zs]e path parameters

---
 scripts/css/nature.css | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/css/nature.css b/scripts/css/nature.css
index 0fdcc55a..5fd4fae5 100644
--- a/scripts/css/nature.css
+++ b/scripts/css/nature.css
@@ -273,6 +273,7 @@ table {
 
 td[colspan]:not([colspan="1"]) {
     background: #eeeeee;
+    text-transform: capitalize;
 }
 
 thead {