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.
This commit is contained in:
George Joseph 2023-06-26 06:55:49 -06:00
parent 248b0637ff
commit 812156edfd
5 changed files with 79 additions and 67 deletions

View File

@ -1118,7 +1118,8 @@ ifeq ($(PYTHON),:)
else else
@$(INSTALL) -d doc/rest-api @$(INSTALL) -d doc/rest-api
$(PYTHON) rest-api-templates/make_ari_stubs.py \ $(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 endif
check-alembic: makeopts check-alembic: makeopts

View File

@ -1,73 +1,75 @@
{{#api_declaration}} {{#api_declaration}}
h1. {{name_title}} # {{name_title}}
|| Method || Path<br>h5. Parameters are case-sensitive || Return Model || Summary ||
| Method | Path (Parameters are case-sensitive) | Return Model | Summary |
|:------ |:------------------------------------ |:------------ |:------- |
{{#apis}} {{#apis}}
{{#operations}} {{#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}} {{/operations}}
{{/apis}} {{/apis}}
{{#apis}} {{#apis}}
{{#operations}} {{#operations}}
{anchor:{{nickname}}} ---
h2. {{nickname}}: {{http_method}} {{wiki_path}} [//]: # (anchor:{{nickname}})
## {{nickname}}
### {{http_method}} {{wiki_path}}
{{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}} {{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}}
{{#has_path_parameters}} {{#has_path_parameters}}
h3. Path parameters ### Path parameters
Parameters are case-sensitive. Parameters are case-sensitive.
{{#path_parameters}} {{#path_parameters}}
* {{name}}: _{{data_type}}_ - {{{wiki_description}}} * {{name}}: _{{data_type}}_ - {{{wiki_description}}}
{{#default_value}} {{#default_value}}
** Default: {{default_value}} * Default: {{default_value}}
{{/default_value}} {{/default_value}}
{{#wiki_allowable_values}} {{#wiki_allowable_values}}
** {{wiki_allowable_values}} * {{wiki_allowable_values}}
{{/wiki_allowable_values}} {{/wiki_allowable_values}}
{{/path_parameters}} {{/path_parameters}}
{{/has_path_parameters}} {{/has_path_parameters}}
{{#has_query_parameters}} {{#has_query_parameters}}
h3. Query parameters ### Query parameters
{{#query_parameters}} {{#query_parameters}}
* {{name}}: _{{data_type}}_ -{{#required}} *(required)*{{/required}} {{{wiki_description}}} * {{name}}: _{{data_type}}_ -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
{{#default_value}} {{#default_value}}
** Default: {{default_value}} * Default: {{default_value}}
{{/default_value}} {{/default_value}}
{{#wiki_allowable_values}} {{#wiki_allowable_values}}
** {{wiki_allowable_values}} * {{wiki_allowable_values}}
{{/wiki_allowable_values}} {{/wiki_allowable_values}}
{{#allow_multiple}} {{#allow_multiple}}
** Allows comma separated values. * Allows comma separated values.
{{/allow_multiple}} {{/allow_multiple}}
{{/query_parameters}} {{/query_parameters}}
{{/has_query_parameters}} {{/has_query_parameters}}
{{#has_body_parameter}} {{#has_body_parameter}}
h3. Body parameter
### Body parameter
{{#body_parameter}} {{#body_parameter}}
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}} * {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
{{#allow_multiple}} {{#allow_multiple}}
** Allows comma separated values. * Allows comma separated values.
{{/allow_multiple}} {{/allow_multiple}}
{{/body_parameter}} {{/body_parameter}}
{{/has_body_parameter}} {{/has_body_parameter}}
{{#has_header_parameters}} {{#has_header_parameters}}
h3. Header parameters ### Header parameters
{{#header_parameters}} {{#header_parameters}}
* {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}} * {{name}}: {{data_type}}{{#default_value}} = {{default_value}}{{/default_value}} -{{#required}} *(required)*{{/required}} {{{wiki_description}}}
{{#allow_multiple}} {{#allow_multiple}}
** Allows comma separated values. * Allows comma separated values.
{{/allow_multiple}} {{/allow_multiple}}
{{/header_parameters}} {{/header_parameters}}
{{/has_header_parameters}} {{/has_header_parameters}}
{{#has_error_responses}} {{#has_error_responses}}
h3. Error Responses ### Error Responses
{{#error_responses}} {{#error_responses}}
* {{code}} - {{{wiki_reason}}} * {{code}} - {{{wiki_reason}}}
{{/error_responses}} {{/error_responses}}

View File

@ -28,7 +28,7 @@ except ImportError:
import os.path import os.path
from asterisk_processor import AsteriskProcessor from asterisk_processor import AsteriskProcessor
from optparse import OptionParser from argparse import ArgumentParser as ArgParser
from swagger_model import ResourceListing from swagger_model import ResourceListing
from transform import Transform from transform import Transform
@ -42,55 +42,61 @@ def rel(file):
""" """
return os.path.join(TOPDIR, 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): def main(argv):
parser = OptionParser(usage="Usage %prog [resources.json] [destdir]") description = (
'Command line utility to export ARI documentation to markdown'
)
(options, args) = parser.parse_args(argv) 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)
if len(args) != 3: args = parser.parse_args()
parser.error("Wrong number of arguments") if not args:
return
source = args[1]
dest_dir = args[2]
renderer = pystache.Renderer(search_dirs=[TOPDIR], missing_tags='strict') 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 # Build the models
base_dir = os.path.dirname(source) base_dir = os.path.dirname(args.resources)
resources = ResourceListing().load_file(source, processor) resources = ResourceListing().load_file(args.resources, processor)
for api in resources.apis: for api in resources.apis:
api.load_api_declaration(base_dir, processor) api.load_api_declaration(base_dir, processor)
# Render the templates # Render the templates
for api in resources.apis: for api in resources.apis:
for transform in API_TRANSFORMS: for transform in API_TRANSFORMS:
transform.render(renderer, api, dest_dir) transform.render(renderer, api, args.source_dir)
for transform in RESOURCES_TRANSFORMS: for transform in RESOURCES_TRANSFORMS:
transform.render(renderer, resources, dest_dir) transform.render(renderer, resources, args.source_dir)
if __name__ == "__main__": if __name__ == "__main__":
sys.exit(main(sys.argv) or 0) sys.exit(main(sys.argv) or 0)

View File

@ -1,18 +1,18 @@
{toc} ---
title: Asterisk REST Data Models
---
# Asterisk REST Data Models
{{#apis}} {{#apis}}
{{#api_declaration}} {{#api_declaration}}
{{#models}} {{#models}}
h1. {{id}} ## {{id}}
{{#extends}}Base type: [{{extends}}|#{{extends}}]{{/extends}} {{#extends}}Base type: [{{extends}}](#{{extends}}){{/extends}}
{{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}|#{{id}}]{{/all_subtypes}}{{/has_subtypes}} {{#has_subtypes}}Subtypes:{{#all_subtypes}} [{{id}}](#{{id}}){{/all_subtypes}}{{/has_subtypes}}
{{#wiki_description}} ### Model
``` javascript title="{{id}}" linenums="1"
{{{wiki_description}}}
{{/wiki_description}}
{code:language=javascript|collapse=true}
{{{model_json}}} {{{model_json}}}
{code} ```
### Properties
{{#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}} * {{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}} {{/properties}}

View File

@ -332,6 +332,7 @@ class SwaggerType(Stringify):
self.is_discriminator = None self.is_discriminator = None
self.is_list = None self.is_list = None
self.singular_name = None self.singular_name = None
self.lc_singular_name = None
self.is_primitive = None self.is_primitive = None
self.is_binary = None self.is_binary = None
@ -345,8 +346,10 @@ class SwaggerType(Stringify):
self.is_list = type_param is not None self.is_list = type_param is not None
if self.is_list: if self.is_list:
self.singular_name = type_param self.singular_name = type_param
self.lc_singular_name = type_param.lower()
else: else:
self.singular_name = self.name self.singular_name = self.name
self.lc_singular_name = self.name.lower()
self.is_primitive = self.singular_name in SWAGGER_PRIMITIVES self.is_primitive = self.singular_name in SWAGGER_PRIMITIVES
self.is_binary = (self.singular_name == 'binary') self.is_binary = (self.singular_name == 'binary')
processor.process_type(self, context) processor.process_type(self, context)