paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-11 09:27:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

api docs: Redesign visuals for documenting arguments.

Browse Source 
The previous system for documenting arguments was very ugly if any of
the examples or descriptions were wrong.  After thinking about this
for a while, I concluded the core problem was that a table was the
wrong design element to use for API parameters, and we'd be much
better off with individual card-type widgets instead.

This rewrites the API arguments documentation implementation to use a
basic sort of card-like system with some basic styling; I think the
result is a lot more readable, and it's a lot more clear how we would
add additional OpenAPI details (like parameter types) to the
documentation.
This commit is contained in:
Tim Abbott
2020-03-26 21:03:26 -07:00
parent 43996106d8
commit 820f0e275e
4 changed files with 61 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
zerver/lib/bugdown/api_arguments_table_generator.py
View File

@@ -1,6 +1,6 @@
import re
import os
import ujson
import json
from django.utils.html import escape as escape_html
from markdown.extensions import Extension
@@ -67,7 +67,7 @@ class APIArgumentsTablePreprocessor(Preprocessor):
raise e
else:
with open(filename, 'r') as fp:
json_obj = ujson.load(fp)
json_obj = json.load(fp)
arguments = json_obj[doc_name]
if arguments:
@@ -89,29 +89,17 @@ class APIArgumentsTablePreprocessor(Preprocessor):
return lines
def render_table(self, arguments: List[Dict[str, Any]]) -> List[str]:
# TODO: Fix naming now that this no longer renders a table.
table = []
beginning = """
<table class="table">
<thead>
<tr>
<th>Argument</th>
<th>Example</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
"""
tr = """
<tr>
<td><code>{argument}</code></td>
<td class="json-api-example"><code>{example}</code></td>
<td>{required}</td>
<td>{description}</td>
</tr>
"""
table.append(beginning)
argument_template = """
<div class="api-argument">
<p class="api-argument-name"><strong>{argument}</strong> {required}</p>
<div class="api-example">
<span class="api-argument-example-label">Example</span>: <code>{example}</code>
</div>
<div class="api-description">{description}</div>
<hr />
</div>"""
md_engine = markdown.Markdown(extensions=[])
@@ -125,23 +113,20 @@ class APIArgumentsTablePreprocessor(Preprocessor):
default = argument.get('schema', {}).get('default')
if default is not None:
description += '\nDefaults to `{}`.'.format(ujson.dumps(default))
description += '\nDefaults to `{}`.'.format(json.dumps(default))
# TODO: Swagger allows indicating where the argument goes
# (path, querystring, form data...). A column in the table should
# be added for this.
table.append(tr.format(
# TODO: OpenAPI allows indicating where the argument goes
# (path, querystring, form data...). We should document this detail.
table.append(argument_template.format(
argument=argument.get('argument') or argument.get('name'),
# Show this as JSON to avoid changing the quoting style, which
# may cause problems with JSON encoding.
example=escape_html(ujson.dumps(argument['example'])),
required='Yes' if argument.get('required') else 'No',
example=escape_html(json.dumps(argument['example'])),
required='<span class="api-argument-required">required</span>' if argument.get('required')
else '<span class="api-argument-optional">optional</span>',
description=md_engine.convert(description),
))
table.append("</tbody>")
table.append("</table>")
return table
def makeExtension(*args: Any, **kwargs: str) -> MarkdownArgumentsTableGenerator: