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)

diff --git a/Makefile b/Makefile
index 3da203982828d4e0d5263a15a3e2d1d51d6ff4ce..546a316c4d628e243c7a27246a2915ca20082cac 100644 (file)
--- 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 a51c3e6ce607cbcc60ede4e05d0f93ea167b18d7..343aa11b5c4951ebec08204b3636032f7c649ca5 100644 (file)
--- 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}}

diff --git a/rest-api-templates/make_ari_stubs.py b/rest-api-templates/make_ari_stubs.py
index 9a340d3fb2df875b640325a2b1381228a983a1ef..a6c6a2452749de6b76c39b2b89a82b01dd46d864 100755 (executable)
--- 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 2bc1e467f1afcac769889f9933a8cf9eea682d49..fe70f08595b1b87015f442712904196d11c2f604 100644 (file)
--- 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 50c5fb07b387901a4de0204df50a649f136f299a..57bce0cbfa15ac24769120d6de78a306e035de76 100644 (file)
--- 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)