Reworked docs rendering using jinja2.

lib/python/qmk/cli/__init__.py

@@ -16,7 +16,8 @@ import_names = {
     # A mapping of package name to importable name
     'pep8-naming': 'pep8ext_naming',
     'pyusb': 'usb.core',
-    'qmk-dotty-dict': 'dotty_dict'
+    'qmk-dotty-dict': 'dotty_dict',
+    'Jinja2': 'jinja2'
 }
 
 safe_commands = [

lib/python/qmk/xap/common.py

@@ -1,10 +1,21 @@
 """This script handles the XAP protocol data files.
 """
-import re
+import os
 import hjson
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+from qmk.constants import QMK_FIRMWARE
 from typing import OrderedDict
 
-from qmk.constants import QMK_FIRMWARE
+
+def _get_jinja2_env(data_templates_xap_subdir: str):
+    templates_dir = os.path.join(QMK_FIRMWARE, 'data', 'templates', 'xap', data_templates_xap_subdir)
+    j2 = Environment(loader=FileSystemLoader(templates_dir), autoescape=select_autoescape())
+    return j2
+
+
+def render_xap_output(data_templates_xap_subdir, file_to_render, defs):
+    j2 = _get_jinja2_env(data_templates_xap_subdir)
+    return j2.get_template(file_to_render).render(xap=defs, xap_str=hjson.dumps(defs))
 
 
 def _merge_ordered_dicts(dicts):

lib/python/qmk/xap/gen_docs/generator.py

@@ -2,64 +2,7 @@
 """
 import hjson
 from qmk.constants import QMK_FIRMWARE
-from qmk.xap.common import get_xap_definition_files, update_xap_definitions
-
-
-def _update_type_docs(overall):
-    defs = overall['type_docs']
-
-    type_docs = []
-    for (k, v) in sorted(defs.items(), key=lambda x: x[0]):
-        type_docs.append(f'| _{k}_ | {v} |')
-
-    desc_str = "\n".join(type_docs)
-
-    overall['documentation']['!type_docs!'] = f'''\
-| Name | Definition |
-| -- | -- |
-{desc_str}
-'''
-
-
-def _update_term_definitions(overall):
-    defs = overall['term_definitions']
-
-    term_descriptions = []
-    for (k, v) in sorted(defs.items(), key=lambda x: x[0]):
-        term_descriptions.append(f'| _{k}_ | {v} |')
-
-    desc_str = "\n".join(term_descriptions)
-
-    overall['documentation']['!term_definitions!'] = f'''\
-| Name | Definition |
-| -- | -- |
-{desc_str}
-'''
-
-
-def _update_response_flags(overall):
-    flags = overall['response_flags']['bits']
-    for n in range(0, 8):
-        if str(n) not in flags:
-            flags[str(n)] = {"name": "-", "description": "-"}
-
-    header = '| ' + " | ".join([f'Bit {n}' for n in range(7, -1, -1)]) + ' |'
-    dividers = '|' + "|".join(['--' for n in range(7, -1, -1)]) + '|'
-    bit_names = '| ' + " | ".join([flags[str(n)]['name'] for n in range(7, -1, -1)]) + ' |'
-
-    bit_descriptions = ''
-    for n in range(7, -1, -1):
-        bit_desc = flags[str(n)]
-        if bit_desc['name'] != '-':
-            desc = bit_desc['description']
-            bit_descriptions = bit_descriptions + f'\n* `Bit {n}`: {desc}'
-
-    overall['documentation']['!response_flags!'] = f'''\
-{header}
-{dividers}
-{bit_names}
-{bit_descriptions}
-'''
+from qmk.xap.common import get_xap_definition_files, update_xap_definitions, render_xap_output
 
 
 def generate_docs():
@@ -69,27 +12,18 @@ def generate_docs():
 
     overall = None
     for file in get_xap_definition_files():
-
         overall = update_xap_definitions(overall, hjson.load(file.open(encoding='utf-8')))
 
-        try:
-            if 'type_docs' in overall:
-                _update_type_docs(overall)
-            if 'term_definitions' in overall:
-                _update_term_definitions(overall)
-            if 'response_flags' in overall:
-                _update_response_flags(overall)
-        except:
-            print(hjson.dumps(overall))
-            exit(1)
+        # Inject dummy bits for unspecified response flags
+        for n in range(0, 8):
+            if str(n) not in overall['response_flags']['bits']:
+                overall['response_flags']['bits'][str(n)] = {'name': '', 'description': '', 'define': '-'}
 
         output_doc = QMK_FIRMWARE / "docs" / f"{file.stem}.md"
         docs_list.append(output_doc)
-
+        output = render_xap_output('docs', 'docs.md.j2', overall)
         with open(output_doc, "w", encoding='utf-8') as out_file:
-            for e in overall['documentation']['order']:
-                out_file.write(overall['documentation'][e].strip())
-                out_file.write('\n\n')
+            out_file.write(output)
 
     output_doc = QMK_FIRMWARE / "docs" / f"xap_protocol.md"
     with open(output_doc, "w", encoding='utf-8') as out_file: