From 44de5023cb3c1a164e6cfb49eb3ddaae74a83fca Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Mon, 17 Jun 2024 23:45:48 -0700 Subject: [PATCH] docs: Updated scripts for rpc examples This update will add lightning-cli examples and make examples heading collapsible. - The JSON EXAMPLES heading is collapsible now - Examples in lightning-cli format also - manpage examples have better formatting Changelog-None. --- tools/fromschema.py | 65 +++++++++++++++++++++++++++++++++++---------- tools/md2man.sh | 4 ++- 2 files changed, 54 insertions(+), 15 deletions(-) diff --git a/tools/fromschema.py b/tools/fromschema.py index 1123daccbdc4..1169dbb5ee83 100755 --- a/tools/fromschema.py +++ b/tools/fromschema.py @@ -291,6 +291,53 @@ def output_members(sub, indent=''): output_members(ifclause['then'], indent + ' ') +def create_shell_command(rpc, example): + """Output shell command for the request example""" + output('```shell\n') + shell_command = f'lightning-cli {rpc} ' + if 'params' in example['request']: + if isinstance(example['request']['params'], list): + shell_command += ' '.join(f'"{item}"' for item in example['request']['params']) + elif example['request']['params'].items(): + shell_command += '-k ' + for k, v in example['request']['params'].items(): + # If the value is a string, wrap it in double quotes + # otherwise, keep the json as is and wrap the whole value in single quotes + # Example 1: wrap route list in single quotes + # lightning-cli check -k "command_to_check"="sendpay" "route"='[{"amount_msat": 1011, "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59", "delay": 20, "channel": "1x1x1"}, {"amount_msat": 1000, "id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d", "delay": 10, "channel": "2x2x2"}]' "payment_hash"="0000000000000000000000000000000000000000000000000000000000000000" + # Example 2: keep subcommand value ("slowcmd") in double quotes + # lightning-cli check -k "command_to_check"="dev" "subcommand"="slowcmd" "msec"=1000 + if isinstance(v, str): + shell_command += f'"{k}"="{v}" ' + elif isinstance(v, int): + shell_command += f'"{k}"={v} ' + else: + shell_command += f'"{k}"=\'' + json.dumps(v) + '\' ' + shell_command = shell_command.strip() + output(shell_command + '\n') + output('```\n') + + +def create_expandable(title, rpc, examples): + """Output example/s with request and response in collapsible header""" + output('\n
\n') + output('\n') + output(f'{title}
\n') + output('\n\n') + for i, example in enumerate(examples): + output('{}**Example {}**: {}\n'.format('' if i == 0 else '\n', i + 1, '\n'.join(example.get('description', '')))) + output('\nRequest:\n') + output('```json\n') + output(json.dumps(example['request'], indent=2).strip() + '\n') + output('```\n') + create_shell_command(rpc, example) + output('\nResponse:\n') + output('```json\n') + output(json.dumps(example['response'], indent=2).strip() + '\n') + output('```\n') + output('
') + + def generate_header(schema): """Generate lines for rpc title and synopsis with request parameters""" output_title(esc_underscores(''.join(['lightning-', schema['rpc'], ' -- ', schema['title']])), '=', 0, 1) @@ -433,29 +480,19 @@ def generate_body(schema): def generate_footer(schema): """Output sections which should be printed after return value""" - first_matching_key = True for key in FOOTER_KEY_SEQUENCE: if key not in schema: continue - output_title(key.replace('_', ' ').upper(), '-', 1 if first_matching_key else 2) - first_matching_key = False if key == 'see_also': + output_title(key.replace('_', ' ').upper(), '-', 1) # Wrap see_also list with comma separated values output(esc_underscores(', '.join(schema[key]))) elif key == 'json_example' and len(schema[key]) > 0: - for i, example in enumerate(schema.get(key, [])): - output('{}**Example {}**: {}\n'.format('' if i == 0 else '\n\n', i + 1, '\n'.join(example.get('description', '')))) - output('\nRequest:\n') - output('```json\n') - output(json.dumps(example['request'], indent=2).strip() + '\n') - output('```') - output('\nResponse:\n') - output('```json\n') - output(json.dumps(example['response'], indent=2).strip() + '\n') - output('```') + create_expandable('EXAMPLE', schema['rpc'], schema.get('json_example', [])) else: + output_title(key.replace('_', ' ').upper(), '-', 1) outputs(schema[key], '\n') - output('\n') + output('\n') def main(schemafile, markdownfile): diff --git a/tools/md2man.sh b/tools/md2man.sh index 5052459eb46b..1a5c8597103b 100755 --- a/tools/md2man.sh +++ b/tools/md2man.sh @@ -13,4 +13,6 @@ TITLE="$(basename "$(basename "$SOURCE" .md)" ."$SECTION" | tr '[:lower:]' '[:up # format. mrkd used to do this for us, lowdown(1) doesn't. TITLELINE="$(head -n1 "$SOURCE")" -(echo "NAME"; echo "----"; echo "$TITLELINE"; tail -n +3 "$SOURCE") | $LOWDOWN -s --out-no-smarty -Tman -m "title:$TITLE" -m "section:$SECTION" -m "source:Core Lightning $VERSION" -m "shiftheadinglevelby:-1" +SOURCE=$(tail -n +3 "$SOURCE" | sed -E ':a;N;$!ba;s#\s*
\s*\s*EXAMPLE
\s*#\n\nEXAMPLE\n------------\n#g; s#Request:#Request:\n#g; s#Response:#Response:\n#g; s#lightning-cli#\nOR\n\nlightning-cli#g;') + +(echo "NAME"; echo "----"; echo "$TITLELINE"; echo "$SOURCE") | $LOWDOWN -s --out-no-smarty -Tman -m "title:$TITLE" -m "section:$SECTION" -m "source:Core Lightning $VERSION" -m "shiftheadinglevelby:-1"