gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2025-03-12 22:44:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add command to produce docs for keyboard/keymap level xap.hjson

Browse Source
This commit is contained in:
zvecr 2023-11-01 03:04:27 +00:00
parent 555b290f55
commit 76970e1d98
1 changed files with 28 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
lib/python/qmk/cli/xap/generate_docs.py
View File

@ -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)