wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' into daniel/multipleexamples

Browse source
This commit is contained in:
Daniel Wagner-Hall 2015-11-25 14:29:33 +00:00
commit 4faede73a1
32 changed files with 1270 additions and 331 deletions
Download patch file Download diff file Expand all files Collapse all files

22
templating/build.py
View file

@ -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

15
templating/matrix_templates/templates/common-event-fields.tmpl
View file

@ -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"]) }}

15
templating/matrix_templates/templates/events.tmpl
View file

@ -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{% if examples | length > 1 %}s{% endif %}:

32
templating/matrix_templates/templates/http-api.tmpl
View file

@ -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 -%}
@ -12,18 +14,11 @@
{{":Requires auth: Yes." if endpoint.requires_auth else "" }}
Request format:
=========================================== ================= ===========================================
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 -%}
=========================================== ================= ===========================================
{% if (endpoint.req_param_by_loc | length) %}
{{ tables.split_paramtable(endpoint.req_param_by_loc) }}
{% else %}
`No parameters`
{% endif %}
{% if endpoint.res_tables|length > 0 -%}
Response format:
@ -31,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 -%}

15
templating/matrix_templates/templates/msgtypes.tmpl
View file

@ -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:

104
templating/matrix_templates/templates/tables.tmpl Normal file
View file

@ -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 %}

23
templating/matrix_templates/units.py
View file

@ -122,10 +122,12 @@ def get_json_schema_object_fields(obj, enforce_title=False, include_parents=Fals
"x-pattern", "string"
)
value_type = "{%s: %s}" % (key, nested_object[0]["title"])
value_id = "%s: %s" % (key, nested_object[0]["title"])
if not nested_object[0].get("no-table"):
tables += nested_object
else:
value_type = "{string: %s}" % prop_val
value_type = "{string: %s}" % (prop_val,)
value_id = "string: %s" % (prop_val,)
else:
nested_object = get_json_schema_object_fields(
props[key_name],
@ -133,6 +135,7 @@ def get_json_schema_object_fields(obj, enforce_title=False, include_parents=Fals
include_parents=include_parents,
)
value_type = "{%s}" % nested_object[0]["title"]
value_id = "%s" % (nested_object[0]["title"],)
if not nested_object[0].get("no-table"):
tables += nested_object
@ -145,12 +148,14 @@ def get_json_schema_object_fields(obj, enforce_title=False, include_parents=Fals
include_parents=include_parents,
)
value_type = "[%s]" % nested_object[0]["title"]
value_id = "%s" % (nested_object[0]["title"],)
tables += nested_object
else:
value_type = props[key_name]["items"]["type"]
if isinstance(value_type, list):
value_type = " or ".join(value_type)
value_type = "[%s]" % value_type
value_id = "%s" % (value_type,)
array_enums = props[key_name]["items"].get("enum")
if array_enums:
if len(array_enums) > 1:
@ -164,6 +169,7 @@ def get_json_schema_object_fields(obj, enforce_title=False, include_parents=Fals
)
else:
value_type = props[key_name]["type"]
value_id = props[key_name]["type"]
if props[key_name].get("enum"):
if len(props[key_name].get("enum")) > 1:
value_type = "enum"
@ -184,6 +190,7 @@ def get_json_schema_object_fields(obj, enforce_title=False, include_parents=Fals
fields["rows"].append({
"key": key_name,
"type": value_type,
"id": value_id,
"required": required,
"desc": desc,
"req_str": "**Required.** " if required else ""
@ -313,10 +320,16 @@ class MatrixUnits(Units):
if req_tables > 1:
for table in req_tables[1:]:
nested_key_name = [
s["key"] for s in req_tables[0]["rows"] if
s["type"] == ("{%s}" % (table["title"],))
][0]
nested_key_name = {
"key": s["key"]
for rtable in req_tables
for s in rtable["rows"]
if s["id"] == table["title"]
}.get("key", None)
if nested_key_name is None:
raise Exception("Failed to find table for %r" % (table["title"],))
for row in table["rows"]:
row["key"] = "%s.%s" % (nested_key_name, row["key"])