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.
2 years ago · 359f9434de
parent b974a8f9eb
commit 359f9434de
5 changed files with 81 additions and 69 deletions
--- a/3
+++ b/3
@ -1119,7 +1119,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
--- 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<br>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}}
--- 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 21'
-
-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)
--- 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}}
--- 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)