Skip to content

Commit

Permalink
docs: Updated scripts for rpc examples
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
ShahanaFarooqui authored and rustyrussell committed Jun 19, 2024
1 parent a4e7079 commit 44de502
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 15 deletions.
65 changes: 51 additions & 14 deletions tools/fromschema.py
Original file line number Diff line number Diff line change
Expand Up @@ -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<details>\n')
output('<summary>\n')
output(f'<span style="font-size: 1.5em; font-weight: bold;">{title}</span><br><hr>\n')
output('</summary>\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('</details>')


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)
Expand Down Expand Up @@ -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):
Expand Down
4 changes: 3 additions & 1 deletion tools/md2man.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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*<details>\s*<summary>\s*<span style="font-size: 1\.5em; font-weight: bold;">EXAMPLE</span><br><hr>\s*</summary>#\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"

0 comments on commit 44de502

Please sign in to comment.