From 2e30f96d92d1f942a98ca0b3bb31fde1599359b9 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Mon, 4 Nov 2024 18:36:59 -0800 Subject: [PATCH] doc: Updated section for Generating Examples in Schema --- .../writing-json-schemas.md | 65 +++++++++++++++---- 1 file changed, 51 insertions(+), 14 deletions(-) diff --git a/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md b/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md index 322e27e636ee..d895e92e116f 100644 --- a/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md +++ b/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md @@ -62,22 +62,59 @@ To add conditional fields: it can be defined as `"dependentUpon": { "index": ["start", "limit"] }` in the json and it will generate the Markdown syntax as `[*index* [*start*] [*limit*]]`. -### Re-generate examples listed in rpc schemas (doc/schemas/lightning-*.json) - -1. The `autogenerate-rpc-examples.py` script regenerates RPC examples for methods listed in `doc/schemas/lightning-*.json` files. -2. It uses our pre-existing pytest suite to perform this task. -3. The script runs a test named `test_generate_examples`, which sets up test nodes, records RPC requests, and captures responses. If you have added an RPC, make sure to add its use to the scripts here. -4. To prevent accidental overwriting of examples with other tests, set the environment variable `GENERATE_EXAMPLES=True` before running the script. -5. By default, all methods are regenerated. To specify which methods to regenerate, set the `REGENERATE` environment variable with a comma-separated list of method names. Eg. `REGENERATE='getinfo,connect'` will only regenerate examples for the getinfo and connect RPCs. -6. The dev-bitcoind-poll is set to 3 seconds. Ensure the `TIMEOUT` environment variable is set to more than 3 seconds to avoid test failures due to a short waiting time for bitcoind responses. -7. To run the script using Poetry, use the following command: +## Generating Examples in Schema +The `tests/autogenerate-rpc-examples.py` test script regenerates RPC examples for methods defined +in `doc/schemas/lightning-*.json`. These examples are located at the end of each schema page, +detailing `shell` and `json` request formats along with their corresponding `json` responses. +The script utilizes the pytest suite to automate this task by running a test, `test_generate_examples`, +that sets up test nodes, records RPC requests, and captures responses. Any new RPC command's examples +should also be included in this scripts. This test only executes example generation if `GENERATE_EXAMPLES=True` +is set, preventing accidental overwrites from unrelated tests. + +### Adding New Examples +1. Define a New Function (if needed): + - If adding multiple examples for the same feature (e.g., `askrene`), create a new function. Otherwise, use an existing relevant function. +2. Add the update_example Method: + - Define examples using `update_example` with parameters: `node method params [res] [description]`. + `node`: Specifies the node to execute the RPC. + `method`: The RPC method name. + `params`: RPC parameters in JSON or list format. + `response (optional)`: Specify for wait commands or pre-recorded responses. + `description (optional)`: Brief explanation of the example. +3. Update the Ignore List: + - Remove the RPC method name from `IGNORE_RPCS_LIST` to include it in the example generation. +4. Run and Refine: + - Run the test multiple times to detect variable values in responses: + ```bash + rm -rf /tmp/ltests* && make -s && VALGRIND=0 TIMEOUT=40 TEST_DEBUG=1 pytest -vvv -n 6 tests/autogenerate-rpc-examples.py + ``` + - Identify changing values, and add them to `REPLACE_RESPONSE_VALUES`: + ```bash + REPLACE_RESPONSE_VALUES.extend([ + {'data_keys': ['xyz'], 'original_value': l1.info['xyz'], 'new_value': NEW_VALUES_LIST['xyz_value_1']} + ]) + ``` + - If `xyz_value_1` already does not exist in the list, add it to `NEW_VALUES_LIST`. +4. Run `make` after the script completes to ensure schema updates are applied in other places too, such as `...msggen/schema.json`. + + +### Avoiding Missing Example Errors (MissingExampleError) + - If an RPC is in progress and lacks examples, add it to `IGNORE_RPCS_LIST` to bypass the auto-generation requirement. + + +### Manually Regenerating Specific Examples +1. By default, all methods are regenerated. To specify which methods to regenerate, set the `REGENERATE` +environment variable with a comma-separated list of method names. Eg. `REGENERATE='getinfo,connect'` will +only regenerate examples for the `getinfo` and `connect` RPCs. +2. To regenerate specific examples, set the REGENERATE environment variable: +```bash +REGENERATE='getinfo,connect' VALGRIND=0 TIMEOUT=10 TEST_DEBUG=1 pytest -vvv -n 6 tests/autogenerate-rpc-examples.py ``` -rm -rf /tmp/ltests* && REGENERATE='getinfo,connect' VALGRIND=0 TIMEOUT=10 TEST_DEBUG=1 pytest -vvv -s -p no:logging -n 6 tests/autogenerate-rpc-examples.py -``` -8. The script saves logs in a file named `autogenerate-examples-status.log`, located in the root directory. -9. After running the script, execute `make` to ensure that the schema has been updated in all relevant locations, such as `...msggen/schema.json`. +3. Logs are saved in `tests/autogenerate-examples-status.log`, and JSON data is in `tests/autogenerate-examples.json`. +4. Run `make` after the script completes to ensure schema updates are applied in other places too, such as `...msggen/schema.json`. + -### JSON Drinking Game! +## JSON Drinking Game! 1. Sip whenever you have an additional comma at the end of a sequence. 2. Sip whenever you omit a comma in a sequence because you cut & paste.