Merge pull request #1463 from turt2live/travis/s2s/pdus-and-edus
Improve documentation around EDUs and PDUs
This commit is contained in:
commit
0f8954d839
8 changed files with 127 additions and 114 deletions
|
@ -189,3 +189,17 @@ class MatrixSections(Sections):
|
|||
template = self.env.get_template("apis.tmpl")
|
||||
apis = self.units.get("apis")
|
||||
return template.render(apis=apis)
|
||||
|
||||
def render_swagger_definition(self):
|
||||
rendered = {}
|
||||
template = self.env.get_template("schema-definition.tmpl")
|
||||
subtitle_title_char = self.units.get("spec_targets")[
|
||||
"relative_title_styles"
|
||||
]["subtitle"]
|
||||
definitions = self.units.get("swagger_definitions")
|
||||
for group, swagger_def in definitions.items():
|
||||
rendered["definition_" + group] = template.render(
|
||||
definition=swagger_def['definition'],
|
||||
examples=swagger_def['examples'],
|
||||
title_kind=subtitle_title_char)
|
||||
return rendered
|
|
@ -0,0 +1,21 @@
|
|||
{% import 'tables.tmpl' as tables -%}
|
||||
|
||||
``{{definition.title}}`` Schema
|
||||
{{(11 + definition.title | length) * title_kind}}
|
||||
|
||||
{% if 'description' in definition %}
|
||||
{{definition.description}}
|
||||
{% endif %}
|
||||
|
||||
{% for table in definition.tables -%}
|
||||
{{"``"+table.title+"``" if table.title else "" }}
|
||||
{{ tables.paramtable(table.rows) }}
|
||||
{% endfor %}
|
||||
|
||||
Example{% if examples | length > 1 %}s{% endif %}:
|
||||
|
||||
{% for example in examples %}
|
||||
.. code:: json
|
||||
|
||||
{{example | jsonify(4, 4)}}
|
||||
{% endfor %}
|
|
@ -43,6 +43,13 @@ HTTP_APIS = {
|
|||
os.path.join(matrix_doc_dir, "api/push-gateway"): "push",
|
||||
os.path.join(matrix_doc_dir, "api/server-server"): "ss",
|
||||
}
|
||||
SWAGGER_DEFINITIONS = {
|
||||
os.path.join(matrix_doc_dir, "api/application-service/definitions"): "as",
|
||||
os.path.join(matrix_doc_dir, "api/client-server/definitions"): "cs",
|
||||
os.path.join(matrix_doc_dir, "api/identity/definitions"): "is",
|
||||
os.path.join(matrix_doc_dir, "api/push-gateway/definitions"): "push",
|
||||
os.path.join(matrix_doc_dir, "api/server-server/definitions"): "ss",
|
||||
}
|
||||
EVENT_EXAMPLES = os.path.join(matrix_doc_dir, "event-schemas/examples")
|
||||
EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema")
|
||||
CORE_EVENT_SCHEMA = os.path.join(matrix_doc_dir, "event-schemas/schema/core-event-schema")
|
||||
|
@ -654,6 +661,50 @@ class MatrixUnits(Units):
|
|||
apis[group_name] = api
|
||||
return apis
|
||||
|
||||
|
||||
def load_swagger_definitions(self):
|
||||
defs = {}
|
||||
for path, prefix in SWAGGER_DEFINITIONS.items():
|
||||
self._load_swagger_definitions_in_dir(defs, path, prefix)
|
||||
return defs
|
||||
|
||||
def _load_swagger_definitions_in_dir(self, defs, path, prefix, recurse=True):
|
||||
if not os.path.exists(path):
|
||||
return defs
|
||||
for filename in os.listdir(path):
|
||||
filepath = os.path.join(path, filename)
|
||||
if os.path.isdir(filepath) and recurse:
|
||||
safe_name = re.sub(r"[^a-zA-Z0-9_]", "_", filename)
|
||||
dir_prefix = "_".join([prefix, safe_name])
|
||||
# We don't recurse because we have to stop at some point
|
||||
self._load_swagger_definitions_in_dir(
|
||||
defs, filepath, dir_prefix, recurse=False)
|
||||
if not filename.endswith(".yaml"):
|
||||
continue
|
||||
filepath = os.path.join(path, filename)
|
||||
logger.info("Reading swagger definition: %s" % filepath)
|
||||
with open(filepath, "r") as f:
|
||||
# strip .yaml
|
||||
group_name = re.sub(r"[^a-zA-Z0-9_]", "_", filename[:-5])
|
||||
group_name = "%s_%s" % (prefix, group_name)
|
||||
definition = yaml.load(f.read(), OrderedLoader)
|
||||
definition = resolve_references(filepath, definition)
|
||||
if 'type' not in definition:
|
||||
continue
|
||||
try:
|
||||
example = get_example_for_schema(definition)
|
||||
except:
|
||||
example = None
|
||||
pass # do nothing - we don't care
|
||||
if 'title' not in definition:
|
||||
definition['title'] = "NO_TITLE"
|
||||
definition['tables'] = get_tables_for_schema(definition)
|
||||
defs[group_name] = {
|
||||
"definition": definition,
|
||||
"examples": [example] if example is not None else [],
|
||||
}
|
||||
return defs
|
||||
|
||||
def load_common_event_fields(self):
|
||||
"""Parse the core event schema files
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue