feat: add feature to convert json schema to markdown table (autowarefoundation#4656)

* feat: add feature to convert json schema to markdown table

Signed-off-by: Ryohsuke Mitsudome <ryohsuke.mitsudome@tier4.jp>

* fix: fix typo

Signed-off-by: Ryohsuke Mitsudome <ryohsuke.mitsudome@tier4.jp>

* style(pre-commit): autofix

* fix: rename main.py and add some comments for the file

Signed-off-by: Ryohsuke Mitsudome <ryohsuke.mitsudome@tier4.jp>

* style(pre-commit): autofix

* fix: use simplified symbols for minimum and maximum

Signed-off-by: Ryohsuke Mitsudome <ryohsuke.mitsudome@tier4.jp>

* fix: Capitalize the first letter in columns' headers

Signed-off-by: Ryohsuke Mitsudome <ryohsuke.mitsudome@tier4.jp>

---------

Signed-off-by: Ryohsuke Mitsudome <ryohsuke.mitsudome@tier4.jp>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: mitsudome-r

mkdocs.yaml

@@ -55,7 +55,8 @@ plugins:
       regex:
         - ^(?!(.*/)?assets/).*\.(?!(.*\.)?md|(.*\.)?svg|(.*\.)?png|(.*\.)?gif|(.*\.)?jpg).*$
         - ^(.*/)?[^.]*$
-  - macros
+  - macros:
+      module_name: mkdocs_macros
   - mkdocs-video
   - same-dir
   - search

mkdocs_macros.py

@@ -0,0 +1,70 @@
+import json
+
+from tabulate import tabulate
+
+# This file is for defining macros for mkdocs-macros plugin
+# Check https://mkdocs-macros-plugin.readthedocs.io/en/latest/macros/ for the details
+
+
+def format_param_type(param_type):
+    if param_type == "number":
+        return "float"
+    else:
+        return param_type
+
+
+def format_param_range(param):
+    list_of_range = []
+    if "enum" in param.keys():
+        list_of_range.append(param["enum"])
+    if "minimum" in param.keys():
+        list_of_range.append("≥" + str(param["minimum"]))
+    if "exclusiveMinimum" in param.keys():
+        list_of_range.append(">" + str(param["exclusiveMinimum"]))
+    if "maximum" in param.keys():
+        list_of_range.append("≤" + str(param["maximum"]))
+    if "exclusiveMaximum" in param.keys():
+        list_of_range.append("<" + str(param["exclusiveMaximum"]))
+    if "exclusive" in param.keys():
+        list_of_range.append("≠" + str(param["exclusive"]))
+
+    if len(list_of_range) == 0:
+        return "N/A"
+    else:
+        range_in_text = ""
+        for item in list_of_range:
+            if range_in_text != "":
+                range_in_text += "<br/>"
+            range_in_text += str(item)
+        return range_in_text
+
+
+def extract_parameter_info(parameters, namespace=""):
+    params = []
+    for k, v in parameters.items():
+        if v["type"] != "object":
+            param = {}
+            param["Name"] = namespace + k
+            param["Type"] = format_param_type(v["type"])
+            param["Description"] = v["description"]
+            param["Default"] = v["default"]
+            param["Range"] = format_param_range(v)
+            params.append(param)
+        else:  # if the object is namespace, then dive deeper in to json value
+            params.extend(extract_parameter_info(v["properties"], k + "."))
+    return params
+
+
+def format_json(json_data):
+    parameters = list(json_data["definitions"].values())[0]["properties"]
+    # cspell: ignore tablefmt
+    markdown_table = tabulate(extract_parameter_info(parameters), headers="keys", tablefmt="github")
+    return markdown_table
+
+
+def define_env(env):
+    @env.macro
+    def json_to_markdown(json_schema_file_path):
+        with open(json_schema_file_path) as f:
+            data = json.load(f)
+            return format_json(data)

perception/lidar_apollo_segmentation_tvm_nodes/README.md

@@ -49,6 +49,10 @@ The input are non-ground points as a PointCloud2 message from the sensor_msgs pa
 
 The output is a [DetectedObjectsWithFeature](https://github.com/tier4/tier4_autoware_msgs/blob/tier4/universe/tier4_perception_msgs/msg/object_recognition/DetectedObjectsWithFeature.msg).
 
+#### Parameters
+
+{{ json_to_markdown("perception/lidar_apollo_segmentation_tvm_nodes/schema/lidar_apollo_segmentation_tvm_nodes.schema.json") }}
+
 ### Error detection and handling
 
 Abort and warn when the input frame can't be converted to `base_link`.