mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-01-18 05:12:45 +01:00
doc/schemas: generate manpage section from schema.
We start with the listpays manpage. Which is now complete! Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell
parent
2c9eaed294
commit
fdb4953fa9
11
doc/Makefile
11
doc/Makefile
@ -86,12 +86,23 @@ MANPAGES := doc/lightning-cli.1 \
|
||||
|
||||
doc-all: $(MANPAGES) doc/index.rst
|
||||
|
||||
# Some manpages use a schema, so need that added.
|
||||
MARKDOWN_WITH_SCHEMA := $(shell grep -l GENERATE-FROM-SCHEMA $(MANPAGES:=.md))
|
||||
|
||||
# These are hard to use in $(call) functions.
|
||||
LBRACKET=(
|
||||
RBRACKET=)
|
||||
|
||||
$(MARKDOWN_WITH_SCHEMA): doc/lightning-%.7.md: doc/schemas/%.schema.json tools/fromschema.py
|
||||
@if $(call SHA256STAMP_CHANGED); then $(call VERBOSE, "fromschema $@", tools/fromschema.py --markdownfile=$@ doc/schemas/$*.schema.json > $@.tmp && grep -v SHA256STAMP: $@.tmp > $@ && rm -f $@.tmp && $(call SHA256STAMP,[comment]: # $(LBRACKET),$(RBRACKET))); else touch $@; fi
|
||||
|
||||
# mrkd doesn't format nested lists properly, so we fixup with sed (see doc/lightning-connect.7
|
||||
# and https://github.com/refi64/mrkd/issues/4
|
||||
$(MANPAGES): doc/%: doc/%.md
|
||||
@if $(call SHA256STAMP_CHANGED); then $(call VERBOSE, "mrkd $<", mrkd $< $@.tmp && sed -e 's/\(.\)\.RS$$/\1\n.RS/' < $@.tmp > $@ && rm $@.tmp && $(call SHA256STAMP,\\\",)); else touch $@; fi
|
||||
|
||||
$(MANPAGES): $(FORCE)
|
||||
$(MARKDOWN_WITH_SCHEMA): $(FORCE)
|
||||
|
||||
doc/protocol-%.svg: test/test_protocol
|
||||
test/test_protocol --svg < test/commits/$*.script > $@
|
||||
|
||||
77
doc/lightning-listpays.7
generated
77
doc/lightning-listpays.7
generated
@ -12,56 +12,53 @@ single one if either \fIbolt11\fR or \fIpayment_hash\fR was specified\.
|
||||
|
||||
.SH RETURN VALUE
|
||||
|
||||
On success, an array of objects is returned\. Each object contains:
|
||||
On success, an object containing \fBpays\fR is returned\. It is an array of objects, where each object contains:
|
||||
|
||||
.RS
|
||||
.IP \[bu]
|
||||
\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters)
|
||||
.IP \[bu]
|
||||
\fBstatus\fR (string): status of the payment (one of "pending", "failed", "complete")
|
||||
.IP \[bu]
|
||||
\fBcreated_at\fR (u64): the UNIX timestamp showing when this payment was initiated
|
||||
.IP \[bu]
|
||||
\fBdestination\fR (pubkey, optional): the final destination of the payment if known
|
||||
.IP \[bu]
|
||||
\fBlabel\fR (string, optional): the label, if given to sendpay
|
||||
.IP \[bu]
|
||||
\fBbolt11\fR (string, optional): the bolt11 string (if pay supplied one)
|
||||
.IP \[bu]
|
||||
\fBbolt12\fR (string, optional): the bolt12 string (if supplied for pay: \fBexperimental-offers\fR only)\.
|
||||
|
||||
\fIbolt11\fR
|
||||
the \fIbolt11\fR invoice if provided to \fBpay\fR\.
|
||||
.RE
|
||||
|
||||
If \fBstatus\fR is "pending" or "complete":
|
||||
|
||||
\fIbolt12\fR
|
||||
if \fBexperimental-offers\fR is enabled, and \fBpay\fR was a given a bolt12
|
||||
invoice, this field will appear instead of \fIbolt11\fR\.
|
||||
.RS
|
||||
.IP \[bu]
|
||||
\fBamount_sent_msat\fR (msat): the amount we actually sent, including fees
|
||||
.IP \[bu]
|
||||
\fBamount_msat\fR (msat, optional): the amount the destination received, if known
|
||||
|
||||
.RE
|
||||
|
||||
\fIpayment_hash\fR
|
||||
the \fIpayment_hash\fR of the payment\.
|
||||
If \fBstatus\fR is "complete":
|
||||
|
||||
.RS
|
||||
.IP \[bu]
|
||||
\fBpreimage\fR (hex): proof of payment (always 64 characters)
|
||||
.IP \[bu]
|
||||
\fBnumber_of_parts\fR (u64, optional): the number of parts for a successful payment (only if more than one)\.
|
||||
|
||||
\fIstatus\fR
|
||||
one of \fIcomplete\fR, \fIfailed\fR or \fIpending\fR\.
|
||||
.RE
|
||||
|
||||
If \fBstatus\fR is "failed":
|
||||
|
||||
\fIpayment_preimage\fR
|
||||
if \fIstatus\fR is \fIcomplete\fR\.
|
||||
|
||||
|
||||
\fIlabel\fR
|
||||
optional \fIlabel\fR, if provided to \fIpay\fR or \fIsendonion\fR\.
|
||||
|
||||
|
||||
\fIamount_sent_msat\fR
|
||||
total amount sent, in "NNNmsat" format\.
|
||||
|
||||
|
||||
For old payments (pre-0\.7) we didn’t save the \fIbolt11\fR string, so in its
|
||||
place are three other fields:
|
||||
|
||||
|
||||
\fIpayment_hash\fR
|
||||
the hash of the \fIpayment_preimage\fR which will prove payment\.
|
||||
|
||||
|
||||
\fIdestination\fR
|
||||
the final destination of the payment\.
|
||||
|
||||
|
||||
\fIamount_msat\fR
|
||||
the amount the destination received, in "NNNmsat" format\.
|
||||
|
||||
|
||||
These three can all be extracted from \fIbolt11\fR, hence are obsolete\.
|
||||
.RS
|
||||
.IP \[bu]
|
||||
\fBerroronion\fR (hex, optional): the error onion returned on failure, if any\.
|
||||
|
||||
.RE
|
||||
.SH AUTHOR
|
||||
|
||||
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
||||
@ -74,4 +71,4 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
||||
|
||||
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
||||
|
||||
\" SHA256STAMP:5a0e016e18f52ce18484d064c3e659aca2687eeafca4b4365e3037faa1fba53f
|
||||
\" SHA256STAMP:e27d57394bef9bdaf9b99ae0d9050c9044c194ab66f6c94c43b532a86e1a0031
|
||||
|
||||
@ -15,43 +15,27 @@ single one if either *bolt11* or *payment_hash* was specified.
|
||||
RETURN VALUE
|
||||
------------
|
||||
|
||||
On success, an array of objects is returned. Each object contains:
|
||||
[comment]: # (GENERATE-FROM-SCHEMA-START)
|
||||
On success, an object containing **pays** is returned. It is an array of objects, where each object contains:
|
||||
- **payment_hash** (hex): the hash of the *payment_preimage* which will prove payment (always 64 characters)
|
||||
- **status** (string): status of the payment (one of "pending", "failed", "complete")
|
||||
- **created_at** (u64): the UNIX timestamp showing when this payment was initiated
|
||||
- **destination** (pubkey, optional): the final destination of the payment if known
|
||||
- **label** (string, optional): the label, if given to sendpay
|
||||
- **bolt11** (string, optional): the bolt11 string (if pay supplied one)
|
||||
- **bolt12** (string, optional): the bolt12 string (if supplied for pay: **experimental-offers** only).
|
||||
|
||||
*bolt11*
|
||||
the *bolt11* invoice if provided to `pay`.
|
||||
If **status** is "pending" or "complete":
|
||||
- **amount_sent_msat** (msat): the amount we actually sent, including fees
|
||||
- **amount_msat** (msat, optional): the amount the destination received, if known
|
||||
|
||||
*bolt12*
|
||||
if **experimental-offers** is enabled, and `pay` was a given a bolt12
|
||||
invoice, this field will appear instead of *bolt11*.
|
||||
If **status** is "complete":
|
||||
- **preimage** (hex): proof of payment (always 64 characters)
|
||||
- **number_of_parts** (u64, optional): the number of parts for a successful payment (only if more than one).
|
||||
|
||||
*payment_hash*
|
||||
the *payment_hash* of the payment.
|
||||
|
||||
*status*
|
||||
one of *complete*, *failed* or *pending*.
|
||||
|
||||
*payment\_preimage*
|
||||
if *status* is *complete*.
|
||||
|
||||
*label*
|
||||
optional *label*, if provided to *pay* or *sendonion*.
|
||||
|
||||
*amount\_sent\_msat*
|
||||
total amount sent, in "NNNmsat" format.
|
||||
|
||||
For old payments (pre-0.7) we didn’t save the *bolt11* string, so in its
|
||||
place are three other fields:
|
||||
|
||||
*payment\_hash*
|
||||
the hash of the *payment\_preimage* which will prove payment.
|
||||
|
||||
*destination*
|
||||
the final destination of the payment.
|
||||
|
||||
*amount\_msat*
|
||||
the amount the destination received, in "NNNmsat" format.
|
||||
|
||||
These three can all be extracted from *bolt11*, hence are obsolete.
|
||||
If **status** is "failed":
|
||||
- **erroronion** (hex, optional): the error onion returned on failure, if any.
|
||||
[comment]: # (GENERATE-FROM-SCHEMA-END)
|
||||
|
||||
AUTHOR
|
||||
------
|
||||
@ -68,3 +52,4 @@ RESOURCES
|
||||
|
||||
Main web site: <https://github.com/ElementsProject/lightning>
|
||||
|
||||
[comment]: # ( SHA256STAMP:12e7b91fc59ee65b61d9aba4e8586fda8fbb524a7e548ffa36862e204952c46b)
|
||||
|
||||
@ -2,12 +2,14 @@
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [ "pays" ],
|
||||
"properties": {
|
||||
"pays": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"additionalProperties": true,
|
||||
"required": [ "payment_hash", "status", "created_at" ],
|
||||
"properties": {
|
||||
"payment_hash": {
|
||||
"type": "hex",
|
||||
@ -24,25 +26,10 @@
|
||||
"type": "pubkey",
|
||||
"description": "the final destination of the payment if known"
|
||||
},
|
||||
"amount_msat": {
|
||||
"type": "msat",
|
||||
"description": "the amount the destination received, if known (**status** *complete* or *pending*)"
|
||||
},
|
||||
"amount_sent_msat": {
|
||||
"type": "msat",
|
||||
"description": "the amount we actually sent, including fees (**status** *complete* or *pending*)"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "u64",
|
||||
"description": "the UNIX timestamp showing when this payment was initiated"
|
||||
},
|
||||
"preimage": {
|
||||
"type": "hex",
|
||||
"description": "proof of payment, only if (and always if) **status** is *complete*",
|
||||
"FIXME": "we should enforce the status/payment_preimage relation in the schema!",
|
||||
"maxLength": 64,
|
||||
"minLength": 64
|
||||
},
|
||||
"label": {
|
||||
"type": "string",
|
||||
"description": "the label, if given to sendpay"
|
||||
@ -54,19 +41,106 @@
|
||||
"bolt12": {
|
||||
"type": "string",
|
||||
"description": "the bolt12 string (if supplied for pay: **experimental-offers** only)."
|
||||
},
|
||||
"erroronion": {
|
||||
"type": "hex",
|
||||
"description": "the error onion returned on failure, if any."
|
||||
},
|
||||
"number_of_parts": {
|
||||
"type": "u64",
|
||||
"description": "the number of parts for a successful payment (only if more than one, and **status** is *complete*)."
|
||||
}
|
||||
},
|
||||
"required": [ "payment_hash", "status", "created_at" ]
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [ "pending", "complete" ]
|
||||
}
|
||||
}
|
||||
},
|
||||
"then": {
|
||||
"additionalProperties": false,
|
||||
"required": [ "amount_sent_msat" ],
|
||||
"properties": {
|
||||
"payment_hash": { },
|
||||
"status": { },
|
||||
"destination": { },
|
||||
"created_at": { },
|
||||
"label": { },
|
||||
"bolt11": { },
|
||||
"bolt12": { },
|
||||
"preimage": { },
|
||||
"number_of_parts": { },
|
||||
"amount_msat": {
|
||||
"type": "msat",
|
||||
"description": "the amount the destination received, if known"
|
||||
},
|
||||
"amount_sent_msat": {
|
||||
"type": "msat",
|
||||
"description": "the amount we actually sent, including fees"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [ "complete" ]
|
||||
}
|
||||
}
|
||||
},
|
||||
"then": {
|
||||
"additionalProperties": false,
|
||||
"required": [ "preimage" ],
|
||||
"properties": {
|
||||
"payment_hash": { },
|
||||
"status": { },
|
||||
"destination": { },
|
||||
"created_at": { },
|
||||
"label": { },
|
||||
"bolt11": { },
|
||||
"bolt12": { },
|
||||
"amount_msat": { },
|
||||
"amount_sent_msat": { },
|
||||
"preimage": {
|
||||
"type": "hex",
|
||||
"description": "proof of payment",
|
||||
"maxLength": 64,
|
||||
"minLength": 64
|
||||
},
|
||||
"number_of_parts": {
|
||||
"type": "u64",
|
||||
"description": "the number of parts for a successful payment (only if more than one)."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [ "failed" ]
|
||||
}
|
||||
}
|
||||
},
|
||||
"then": {
|
||||
"additionalProperties": false,
|
||||
"required": [ ],
|
||||
"properties": {
|
||||
"payment_hash": { },
|
||||
"status": { },
|
||||
"destination": { },
|
||||
"created_at": { },
|
||||
"label": { },
|
||||
"bolt11": { },
|
||||
"bolt12": { },
|
||||
"erroronion": {
|
||||
"type": "hex",
|
||||
"description": "the error onion returned on failure, if any."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [ "pays" ]
|
||||
}
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user