From 76970e1d98d022a0a5270218cdd1ed9850a97161 Mon Sep 17 00:00:00 2001 From: zvecr Date: Wed, 1 Nov 2023 03:04:27 +0000 Subject: [PATCH] Add command to produce docs for keyboard/keymap level xap.hjson --- lib/python/qmk/cli/xap/generate_docs.py | 33 +++++++++++++++++++++---- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/lib/python/qmk/cli/xap/generate_docs.py b/lib/python/qmk/cli/xap/generate_docs.py index 38fb9d2c270..778da5a5492 100755 --- a/lib/python/qmk/cli/xap/generate_docs.py +++ b/lib/python/qmk/cli/xap/generate_docs.py @@ -5,7 +5,17 @@ import hjson from milc import cli from qmk.constants import QMK_FIRMWARE -from qmk.xap.common import get_xap_definition_files, update_xap_definitions, render_xap_output +from qmk.path import normpath +from qmk.commands import dump_lines +from qmk.keyboard import keyboard_completer, keyboard_folder +from qmk.xap.common import get_xap_definition_files, update_xap_definitions, merge_xap_defs, render_xap_output + + +def _patch_spec_for_docs(spec): + # Inject dummy bits for unspecified response flags + for n in range(0, 8): + if str(n) not in spec['response_flags']['bits']: + spec['response_flags']['bits'][str(n)] = {'name': '', 'description': '', 'define': '-'} @cli.subcommand('Generates the XAP protocol documentation.', hidden=False if cli.config.user.developer else True) @@ -18,10 +28,7 @@ def xap_generate_docs(cli): for file in get_xap_definition_files(): overall = update_xap_definitions(overall, hjson.load(file.open(encoding='utf-8'))) - # 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': '-'} + _patch_spec_for_docs(overall) output_doc = QMK_FIRMWARE / "docs" / f"{file.stem}.md" versions.append(overall['version']) @@ -33,3 +40,19 @@ def xap_generate_docs(cli): output = render_xap_output('docs', 'versions.md.j2', overall, versions=versions) with open(output_doc, "w", encoding='utf-8') as out_file: out_file.write(output) + + +@cli.argument('-o', '--output', arg_only=True, type=normpath, help='File to write to') +@cli.argument('-q', '--quiet', arg_only=True, action='store_true', help="Quiet mode, only output error messages") +@cli.argument('-km', '--keymap', help='The keymap\'s name - "default" if not specified') +@cli.argument('-kb', '--keyboard', required=True, type=keyboard_folder, completer=keyboard_completer, help='Name of the keyboard') +@cli.subcommand('Generates the XAP protocol documentation for a given keyboard/keymap.', hidden=False if cli.config.user.developer else True) +def xap_generate_keyboard_docs(cli): + """Generates the XAP protocol documentation for a given keyboard/keymap and producing the corresponding Markdown. + """ + spec = merge_xap_defs(cli.args.keyboard, cli.args.keymap or 'default') + + _patch_spec_for_docs(spec) + + output = render_xap_output('docs', 'docs.md.j2', spec) + dump_lines(cli.args.output, output.split('\n'), cli.args.quiet)