Skip to content

Commit 075f180

Browse files
ShahanaFarooquirustyrussell
authored andcommitted
doc: Add GENERATE_EXAMPLES details
Changelog-None.
1 parent 0a7956b commit 075f180

File tree

2 files changed

+11
-9
lines changed

2 files changed

+11
-9
lines changed

doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,14 @@ To add conditional fields:
6363
generate the Markdown syntax as `[*index* [*start*] [*limit*]]`.
6464

6565
## Generating Examples in Schema
66-
The `tests/autogenerate-rpc-examples.py` test script regenerates RPC examples for methods defined
67-
in `doc/schemas/lightning-*.json`. These examples are located at the end of each schema page,
68-
detailing `shell` and `json` request formats along with their corresponding `json` responses.
69-
The script utilizes the pytest suite to automate this task by running a test, `test_generate_examples`,
70-
that sets up test nodes, records RPC requests, and captures responses. Any new RPC command's examples
71-
should also be included in this scripts. This test only executes example generation if `GENERATE_EXAMPLES=True`
72-
is set, preventing accidental overwrites from unrelated tests.
66+
The `tests/autogenerate-rpc-examples.py` test script regenerates RPC examples for methods defined
67+
in `doc/schemas/lightning-*.json`, if the environment variable `GENERATE_EXAMPLES` is set to 1.
68+
These examples are located at the end of each schema page, detailing `shell` and `json` request
69+
formats along with their corresponding `json` responses. The script utilizes the pytest suite to
70+
automate this task by running a test, `test_generate_examples`, that sets up test nodes, records
71+
RPC requests, and captures responses. Any new RPC command's examples should also be included in
72+
this scripts. This test only executes example generation if `GENERATE_EXAMPLES=1` is set,
73+
preventing accidental overwrites from unrelated tests.
7374

7475
### Adding New Examples
7576
1. Define a New Function (if needed):
@@ -93,7 +94,7 @@ is set, preventing accidental overwrites from unrelated tests.
9394
where `n` can be any number of repetitions. OR by manually running the test multiple times with:
9495

9596
```bash
96-
rm -rf /tmp/ltests* && make -s && VALGRIND=0 TIMEOUT=40 TEST_DEBUG=1 pytest -vvv -n 6 tests/autogenerate-rpc-examples.py
97+
rm -rf /tmp/ltests* && make -s && VALGRIND=0 TIMEOUT=40 TEST_DEBUG=1 GENERATE_EXAMPLES=1 pytest -vvv tests/autogenerate-rpc-examples.py
9798
```
9899

99100
- Identify changing values, and add them to `REPLACE_RESPONSE_VALUES`:
@@ -116,7 +117,7 @@ environment variable with a comma-separated list of method names. Eg. `REGENERAT
116117
only regenerate examples for the `getinfo` and `connect` RPCs.
117118
2. To regenerate specific examples, set the REGENERATE environment variable:
118119
```bash
119-
REGENERATE='getinfo,connect' VALGRIND=0 TIMEOUT=10 TEST_DEBUG=1 pytest -vvv -n 6 tests/autogenerate-rpc-examples.py
120+
REGENERATE='getinfo,connect' VALGRIND=0 TIMEOUT=10 TEST_DEBUG=1 GENERATE_EXAMPLES=1 pytest -vvv tests/autogenerate-rpc-examples.py
120121
```
121122
3. Logs are saved in `tests/autogenerate-examples-status.log`, and JSON data is in `tests/autogenerate-examples.json`.
122123
4. Run `make` after the script completes to ensure schema updates are applied in other places too, such as `...msggen/schema.json`.

doc/contribute-to-core-lightning/testing.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ PYTEST_TESTS="tests/" - Target a specific set of blackbox tests
7878
SLOW_MACHINE=[0|1] - Set sensible defaults for running tests
7979
in resource-constrained environments.
8080
VALGRIND=[0|1] - Run the tests with Valgrind.
81+
GENERATE_EXAMPLES=[0|1] - Generate examples for RPC documentation.
8182
```
8283

8384
#### Troubleshooting

0 commit comments

Comments
 (0)