From a3725fa61f28c4ab71458fa9cda86feaf6c6c79c Mon Sep 17 00:00:00 2001 From: George Joseph Date: Mon, 26 Jun 2023 06:55:49 -0600 Subject: [PATCH] rest-api: Updates for new documentation site The new documentation site uses traditional markdown instead of the Confluence flavored version. This required changes in the mustache templates and the python that generates the files. (cherry picked from commit 812156edfd140c092b45cbe124f8e5c7af7c289c) --- Makefile | 3 +- rest-api-templates/api.wiki.mustache | 40 ++++++------ rest-api-templates/make_ari_stubs.py | 82 +++++++++++++------------ rest-api-templates/models.wiki.mustache | 22 +++---- rest-api-templates/swagger_model.py | 3 + 5 files changed, 81 insertions(+), 69 deletions(-) diff --git a/Makefile b/Makefile index 3da2039828..546a316c4d 100644 --- a/Makefile +++ b/Makefile @@ -1118,7 +1118,8 @@ ifeq ($(PYTHON),:) else @$(INSTALL) -d doc/rest-api $(PYTHON) rest-api-templates/make_ari_stubs.py \ - rest-api/resources.json . + --resources rest-api/resources.json --source-dir $(ASTTOPDIR) \ + --dest-dir $(ASTTOPDIR)/doc/rest-api --docs-prefix ../ endif check-alembic: makeopts diff --git a/rest-api-templates/api.wiki.mustache b/rest-api-templates/api.wiki.mustache index a51c3e6ce6..343aa11b5c 100644 --- a/rest-api-templates/api.wiki.mustache +++ b/rest-api-templates/api.wiki.mustache @@ -1,73 +1,75 @@ {{#api_declaration}} -h1. {{name_title}} - -|| Method || Path
h5. Parameters are case-sensitive || Return Model || Summary || +# {{name_title}} +| Method | Path (Parameters are case-sensitive) | Return Model | Summary | +|:------ |:------------------------------------ |:------------ |:------- | {{#apis}} {{#operations}} -| {{http_method}} | [{{wiki_path}}|#{{nickname}}] | {{#response_class}}{{#is_primitive}}{{name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}|{{wiki_prefix}} REST Data Models#{{singular_name}}]{{/is_primitive}}{{/response_class}} | {{{summary}}} | +| {{http_method}} | [{{wiki_path}}](#{{nickname}}) | {{#response_class}}{{#is_primitive}}{{name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}]({{wiki_prefix}}_Asterisk_REST_Data_Models#{{lc_singular_name}}){{/is_primitive}}{{/response_class}} | {{{summary}}} | {{/operations}} {{/apis}} {{#apis}} {{#operations}} -{anchor:{{nickname}}} -h2. {{nickname}}: {{http_method}} {{wiki_path}} - +--- +[//]: # (anchor:{{nickname}}) +## {{nickname}} +### {{http_method}} {{wiki_path}} {{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}} {{#has_path_parameters}} -h3. Path parameters +### Path parameters Parameters are case-sensitive. {{#path_parameters}} * {{name}}: _{{data_type}}_ - {{{wiki_description}}} {{#default_value}} -** Default: {{default_value}} + * Default: {{default_value}} {{/default_value}} {{#wiki_allowable_values}} -** {{wiki_allowable_values}} + * {{wiki_allowable_values}} {{/wiki_allowable_values}} {{/path_parameters}} {{/has_path_parameters}} {{#has_query_parameters}} -h3. Query parameters +### Query parameters {{#query_parameters}} * {{name}}: _{{data_type}}_ -{{#required}} *(required)*{{/required}} {{{wiki_description}}} {{#default_value}} -** Default: {{default_value}} + * Default: {{default_value}} {{/default_value}} {{#wiki_allowable_values}} -** {{wiki_allowable_values}} + * {{wiki_allowable_values}} {{/wiki_allowable_values}} {{#allow_multiple}} -** Allows comma separated values. + * Allows comma separated values. {{/allow_multiple}} {{/query_parameters}} {{/has_query_parameters}} {{#has_body_parameter}} -h3. Body parameter + +### Body parameter {{#body_parameter}} * {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}} {{#allow_multiple}} -** Allows comma separated values. + * Allows comma separated values. {{/allow_multiple}} {{/body_parameter}} {{/has_body_parameter}} {{#has_header_parameters}} -h3. Header parameters +### Header parameters {{#header_parameters}} * {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}} {{#allow_multiple}} -** Allows comma separated values. + * Allows comma separated values. {{/allow_multiple}} {{/header_parameters}} {{/has_header_parameters}} {{#has_error_responses}} -h3. Error Responses +### Error Responses {{#error_responses}} * {{code}} - {{{wiki_reason}}} {{/error_responses}} diff --git a/rest-api-templates/make_ari_stubs.py b/rest-api-templates/make_ari_stubs.py index 9a340d3fb2..a6c6a24527 100755 --- a/rest-api-templates/make_ari_stubs.py +++ b/rest-api-templates/make_ari_stubs.py @@ -28,7 +28,7 @@ except ImportError: import os.path from asterisk_processor import AsteriskProcessor -from optparse import OptionParser +from argparse import ArgumentParser as ArgParser from swagger_model import ResourceListing from transform import Transform @@ -42,55 +42,61 @@ def rel(file): """ return os.path.join(TOPDIR, file) -WIKI_PREFIX = 'Asterisk 18' - -API_TRANSFORMS = [ - Transform(rel('api.wiki.mustache'), - 'doc/rest-api/%s {{name_title}} REST API.wiki' % WIKI_PREFIX), - Transform(rel('res_ari_resource.c.mustache'), - 'res/res_ari_{{c_name}}.c'), - Transform(rel('ari_resource.h.mustache'), - 'res/ari/resource_{{c_name}}.h'), - Transform(rel('ari_resource.c.mustache'), - 'res/ari/resource_{{c_name}}.c', overwrite=False), -] - -RESOURCES_TRANSFORMS = [ - Transform(rel('models.wiki.mustache'), - 'doc/rest-api/%s REST Data Models.wiki' % WIKI_PREFIX), - Transform(rel('ari.make.mustache'), 'res/ari.make'), - Transform(rel('ari_model_validators.h.mustache'), - 'res/ari/ari_model_validators.h'), - Transform(rel('ari_model_validators.c.mustache'), - 'res/ari/ari_model_validators.c'), -] - - def main(argv): - parser = OptionParser(usage="Usage %prog [resources.json] [destdir]") - - (options, args) = parser.parse_args(argv) - - if len(args) != 3: - parser.error("Wrong number of arguments") + description = ( + 'Command line utility to export ARI documentation to markdown' + ) + + parser = ArgParser(description=description) + parser.add_argument('--resources', type=str, default="rest-api/resources.json", + help="resources.json file to process", required=False) + parser.add_argument('--source-dir', type=str, default=".", + help="Asterisk source directory", required=False) + parser.add_argument('--dest-dir', type=str, default="doc/rest-api", + help="Destination directory", required=False) + parser.add_argument('--docs-prefix', type=str, default="../", + help="Prefix to apply to links", required=False) + + args = parser.parse_args() + if not args: + return - source = args[1] - dest_dir = args[2] renderer = pystache.Renderer(search_dirs=[TOPDIR], missing_tags='strict') - processor = AsteriskProcessor(wiki_prefix=WIKI_PREFIX) + processor = AsteriskProcessor(wiki_prefix=args.docs_prefix) + + API_TRANSFORMS = [ + Transform(rel('api.wiki.mustache'), + '%s/{{name_title}}_REST_API.md' % args.dest_dir), + Transform(rel('res_ari_resource.c.mustache'), + 'res/res_ari_{{c_name}}.c'), + Transform(rel('ari_resource.h.mustache'), + 'res/ari/resource_{{c_name}}.h'), + Transform(rel('ari_resource.c.mustache'), + 'res/ari/resource_{{c_name}}.c', overwrite=False), + ] + + RESOURCES_TRANSFORMS = [ + Transform(rel('models.wiki.mustache'), + '%s/_Asterisk_REST_Data_Models.md' % args.dest_dir), + Transform(rel('ari.make.mustache'), 'res/ari.make'), + Transform(rel('ari_model_validators.h.mustache'), + 'res/ari/ari_model_validators.h'), + Transform(rel('ari_model_validators.c.mustache'), + 'res/ari/ari_model_validators.c'), + ] # Build the models - base_dir = os.path.dirname(source) - resources = ResourceListing().load_file(source, processor) + base_dir = os.path.dirname(args.resources) + resources = ResourceListing().load_file(args.resources, processor) for api in resources.apis: api.load_api_declaration(base_dir, processor) # Render the templates for api in resources.apis: for transform in API_TRANSFORMS: - transform.render(renderer, api, dest_dir) + transform.render(renderer, api, args.source_dir) for transform in RESOURCES_TRANSFORMS: - transform.render(renderer, resources, dest_dir) + transform.render(renderer, resources, args.source_dir) if __name__ == "__main__": sys.exit(main(sys.argv) or 0) diff --git a/rest-api-templates/models.wiki.mustache b/rest-api-templates/models.wiki.mustache index 2bc1e467f1..fe70f08595 100644 --- a/rest-api-templates/models.wiki.mustache +++ b/rest-api-templates/models.wiki.mustache @@ -1,18 +1,18 @@ -{toc} - +--- +title: Asterisk REST Data Models +--- +# Asterisk REST Data Models {{#apis}} {{#api_declaration}} {{#models}} -h1. {{id}} -{{#extends}}Base type: [{{extends}}|#{{extends}}]{{/extends}} -{{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}|#{{id}}]{{/all_subtypes}}{{/has_subtypes}} -{{#wiki_description}} - -{{{wiki_description}}} -{{/wiki_description}} -{code:language=javascript|collapse=true} +## {{id}} +{{#extends}}Base type: [{{extends}}](#{{extends}}){{/extends}} +{{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}](#{{id}}){{/all_subtypes}}{{/has_subtypes}} +### Model +``` javascript title="{{id}}" linenums="1" {{{model_json}}} -{code} +``` +### Properties {{#properties}} * {{name}}: {{#type}}{{#is_primitive}}{{wiki_name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}|#{{singular_name}}]{{/is_primitive}}{{/type}}{{^required}} _(optional)_{{/required}}{{#wiki_description}} - {{{wiki_description}}}{{/wiki_description}} {{/properties}} diff --git a/rest-api-templates/swagger_model.py b/rest-api-templates/swagger_model.py index 50c5fb07b3..57bce0cbfa 100644 --- a/rest-api-templates/swagger_model.py +++ b/rest-api-templates/swagger_model.py @@ -332,6 +332,7 @@ class SwaggerType(Stringify): self.is_discriminator = None self.is_list = None self.singular_name = None + self.lc_singular_name = None self.is_primitive = None self.is_binary = None @@ -345,8 +346,10 @@ class SwaggerType(Stringify): self.is_list = type_param is not None if self.is_list: self.singular_name = type_param + self.lc_singular_name = type_param.lower() else: self.singular_name = self.name + self.lc_singular_name = self.name.lower() self.is_primitive = self.singular_name in SWAGGER_PRIMITIVES self.is_binary = (self.singular_name == 'binary') processor.process_type(self, context)