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

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

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*<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"