Skip to content

Fix documentation website #8819

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rustyrussell merged 5 commits into from
Jan 20, 2026
+109 −91
Merged

Fix documentation website #8819

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
77df585
doc: Add signmessagewithkey to generate documentation
ShahanaFarooqui Jan 6, 2026
a4e9a89
doc: Update json and markdowns to make them .mdx compatible
ShahanaFarooqui Jan 6, 2026
c202c7f
script: Change category slug for better Admin panel management
ShahanaFarooqui Jan 6, 2026
faf9613
script: API v2 accepts `position` param rather than `order`
ShahanaFarooqui Jan 6, 2026
a8aeccd
script: More error checks and logging
ShahanaFarooqui Jan 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 40 additions & 21 deletions .github/scripts/sync-rpc-cmds.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
import os
from urllib.parse import quote
from time import sleep
import requests
import re
from enum import Enum

# readme url
URL = "https://api.readme.com/v2/branches/stable"
CATEGORY_SLUG = "JSON-RPC API Reference"
CATEGORY_SLUG = "JSON-RPC"


class Action(Enum):
Expand All @@ -17,10 +16,12 @@ class Action(Enum):


def getListOfRPCDocs(headers):
response = requests.get(f"{URL}/categories/reference/{quote(CATEGORY_SLUG)}/pages", headers=headers)
response = requests.get(f"{URL}/categories/reference/{CATEGORY_SLUG}/pages", headers=headers)
if response.status_code == 200:
return response.json().get('data', [])
else:
print(f"❌ Failed to get pages: {response.status_code}")
print(response.text)
return []


Expand All @@ -34,7 +35,7 @@ def check_renderable(response, action, title):

renderable = data.get("renderable")
if renderable is None:
# Some endpoints don’t include renderable (e.g. DELETE)
# Some endpoints don't include renderable (e.g. DELETE)
return True

if not renderable.get("status", False):
Expand All @@ -46,53 +47,53 @@ def check_renderable(response, action, title):
return True


def publishDoc(action, title, body, order, headers):
def publishDoc(action, title, body, position, headers):
payload = {
"title": title,
"type": "basic",
"content": {
"body": body,
},
"category": {
"uri": f"/branches/1/categories/reference/{CATEGORY_SLUG}"
"uri": f"/branches/stable/categories/reference/{CATEGORY_SLUG}"
},
"hidden": False,
"order": order,
"position": position,
}

if action == Action.ADD:
payload["slug"] = title
response = requests.post(URL + "/reference", json=payload, headers=headers)
if response.status_code != 201:
print("❌ HTTP ERROR:", response.status_code)
print(f"❌ HTTP ERROR ({response.status_code}):", title)
print(response.text)
return

if not check_renderable(response, action, title):
raise RuntimeError(f"Renderable check failed for {title}")

print("✅ Created", title)
print(f"✅ Created '{title}' at position {position + 1}")

elif action == Action.UPDATE:
response = requests.patch(f"{URL}/reference/{title}", json=payload, headers=headers)
if response.status_code != 200:
print("❌ HTTP ERROR:", response.status_code)
print(f"❌ HTTP ERROR ({response.status_code}):", title)
print(response.text)
return

if not check_renderable(response, action, title):
raise RuntimeError(f"Renderable check failed for {title}")

print("✅ Updated", title)
print(f"✅ Updated '{title}' to position {position + 1}")

elif action == Action.DELETE:
response = requests.delete(f"{URL}/reference/{title}", headers=headers)

if response.status_code != 204:
print("❌ DELETE FAILED:", title)
print(f"❌ DELETE FAILED ({response.status_code}):", title)
print(response.text)
else:
print("🗑️ Deleted", title)
print(f"🗑️ Deleted '{title}' from position {position + 1}")

else:
print("Invalid action")
Expand Down Expand Up @@ -120,8 +121,18 @@ def main():
"Authorization": "Bearer " + os.environ.get("README_API_KEY"),
}

# Validate API key exists
if not os.environ.get("README_API_KEY"):
print("❌ ERROR: README_API_KEY environment variable not set")
return

# path to the rst file from where we fetch all the RPC commands
path_to_rst = "doc/index.rst"

if not os.path.exists(path_to_rst):
print(f"❌ ERROR: File not found: {path_to_rst}")
return

with open(path_to_rst, "r") as file:
rst_content = file.read()

Expand All @@ -130,23 +141,31 @@ def main():

# Compare local and server commands list to get the list of command to add or delete
commands_local_title = set(command[0] for command in commands_from_local)
commands_readme_title = set(command['title'] for command in commands_from_readme)
commands_readme_title = set(command['slug'] for command in commands_from_readme)
commands_to_delete = commands_readme_title - commands_local_title
commands_to_add = commands_local_title - commands_readme_title
for name in commands_to_delete:
publishDoc(Action.DELETE, name, "", 0, headers)
sleep(3)
sleep(1)

if commands_from_local:
order = 0
position = 0
for name, file in commands_from_local:
with open("doc/" + file) as f:
file_path = "doc/" + file
if not os.path.exists(file_path):
print(f"⚠️ WARNING: File not found: {file_path}, skipping {name}")
continue

with open(file_path) as f:
body = f.read()
publishDoc(Action.ADD if name in commands_to_add else Action.UPDATE, name, body, order, headers)
order = order + 1
sleep(3)
action = Action.ADD if name in commands_to_add else Action.UPDATE
publishDoc(action, name, body, position, headers)
position += 1
sleep(1)
else:
print("No commands found in the Manpages block.")
print("⚠️ No commands found in the Manpages block.")

print("\n✨ Sync complete!")


if __name__ == "__main__":
Expand Down
38 changes: 19 additions & 19 deletions contrib/msggen/msggen/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,10 +252,10 @@
"lightning-askrene-listlayers(7)"
],
"author": [
"Rusty Russell <<[email protected]>> is mainly responsible."
"Rusty Russell [[email protected]](mailto:[email protected]) is mainly responsible."
],
"resources": [
"Main web site: <https://github.com/ElementsProject/lightning>"
"Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
],
"examples": [
{
Expand Down Expand Up @@ -3772,9 +3772,9 @@
"type": "object",
"additionalProperties": false,
"rpc": "bkpr-editdescriptionbypaymentid",
"title": "Command to change the description for events with {payment_id} after they're made",
"title": "Command to change the description for events with `payment_id` after they're made",
"description": [
"The **bkpr-editdescriptionbypaymentid** RPC command updates all chain and channel events that match the {payment_id} with the provided {description}"
"The **bkpr-editdescriptionbypaymentid** RPC command updates all chain and channel events that match the `payment_id` with the provided `description`"
],
"request": {
"required": [
Expand Down Expand Up @@ -6730,14 +6730,14 @@
"type": "array",
"description": [
"Alternatives use a simple language to examine the command which is being run:",
" * time: the current UNIX time, e.g. \"time<1656759180\".",
" * id: the node_id of the peer, e.g. \"id=024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605\".",
" * method: the command being run, e.g. \"method=withdraw\".",
" * per: how often the rune can be used, with suffix \"sec\" (default), \"min\", \"hour\", \"day\" or \"msec\", \"usec\" or \"nsec\". e.g. \"per=5sec\".",
" * rate: the rate limit, per minute, e.g. \"rate=60\" is equivalent to \"per=1sec\".",
" * pnum: the number of parameters. e.g. \"pnum<2\".",
" * pnameX: the parameter named X e.g. \"pnamedestination=1RustyRX2oai4EYYDpQGWvEL62BBGqN9T\". NOTE: until v24.05, X had to remove underscores from the parameter name (e.g. `pnameamount_msat` had to be specified as `pnameamountmsat`) but that is now fixed.",
" * parrN: the N'th parameter. e.g. \"parr0=1RustyRX2oai4EYYDpQGWvEL62BBGqN9T\".",
" * time: the current UNIX time, e.g. `time<1656759180`.",
" * id: the node_id of the peer, e.g. `id=024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605`.",
" * method: the command being run, e.g. `method=withdraw`.",
" * per: how often the rune can be used, with suffix \"sec\" (default), \"min\", \"hour\", \"day\" or \"msec\", \"usec\" or \"nsec\". e.g. `per=5sec`.",
" * rate: the rate limit, per minute, e.g. `rate=60` is equivalent to `per=1sec`.",
" * pnum: the number of parameters. e.g. `pnum<2`.",
" * pnameX: the parameter named X e.g. `pnamedestination=1RustyRX2oai4EYYDpQGWvEL62BBGqN9T`. NOTE: until v24.05, X had to remove underscores from the parameter name (e.g. `pnameamount_msat` had to be specified as `pnameamountmsat`) but that is now fixed.",
" * parrN: the N'th parameter. e.g. `parr0=1RustyRX2oai4EYYDpQGWvEL62BBGqN9T`.",
" * pinvX_N: parse the parameter X as an invoice (bolt11 or bolt12) and extract field N for comparison. Fails if parameter X is not present, does not parse, or N is not one of the following field names:",
" * amount",
" * description",
Expand Down Expand Up @@ -7085,12 +7085,12 @@
"",
"However, since brackets and AND conditions within OR are currently not supported for rune creation, we can restructure the conditions as follows:",
"",
"- method^list|method^get|method=summary|method=pay|method=xpay",
"- method/listdatastore",
"- method/pay|per=1day",
"- method/pay|pnameamount\\_msat<100000001",
"- method/xpay|per=1day",
"- method/xpay|pnameamount\\_msat<100000001"
"- `method^list|method^get|method=summary|method=pay|method=xpay`",
"- `method/listdatastore`",
"- `method/pay|per=1day`",
"- `method/pay|pnameamount_msat<100000001`",
"- `method/xpay|per=1day`",
"- `method/xpay|pnameamount_msat<100000001`"
],
"request": {
"id": "example:createrune#9",
Expand Down Expand Up @@ -34648,7 +34648,7 @@
"outputs": {
"type": "array",
"description": [
"Format is like: [{destination1: amount1}, {destination2: amount2}] or [{destination: *all*}]. It supports any number of **confirmed** outputs."
"Format is like: `[{destination1: amount1}, {destination2: amount2}]` or `[{destination: *all*}]`. It supports any number of **confirmed** outputs."
],
"items": {
"type": "outputdesc"
Expand Down
9 changes: 5 additions & 4 deletions doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,16 @@ MARKDOWNPAGES := doc/addgossip.7 \
doc/askrene-age.7 \
doc/askrene-bias-channel.7 \
doc/askrene-bias-node.7 \
doc/askrene-create-layer.7 \
doc/askrene-remove-layer.7 \
doc/askrene-create-channel.7 \
doc/askrene-update-channel.7 \
doc/askrene-create-layer.7 \
doc/askrene-disable-node.7 \
doc/askrene-inform-channel.7 \
doc/askrene-listlayers.7 \
doc/askrene-listreservations.7 \
doc/askrene-remove-layer.7 \
doc/askrene-reserve.7 \
doc/askrene-unreserve.7 \
doc/askrene-update-channel.7 \
doc/autoclean-once.7 \
doc/autoclean-status.7 \
doc/batching.7 \
Expand Down Expand Up @@ -57,7 +57,7 @@ MARKDOWNPAGES := doc/addgossip.7 \
doc/disableoffer.7 \
doc/disconnect.7 \
doc/emergencyrecover.7 \
doc/enableoffer.7 \
doc/enableoffer.7 \
doc/exposesecret.7 \
doc/feerates.7 \
doc/fetchbip353.7 \
Expand Down Expand Up @@ -133,6 +133,7 @@ MARKDOWNPAGES := doc/addgossip.7 \
doc/showrunes.7 \
doc/signinvoice.7 \
doc/signmessage.7 \
doc/signmessagewithkey.7 \
doc/signpsbt.7 \
doc/splice_init.7 \
doc/splice_signed.7 \
Expand Down
1 change: 1 addition & 0 deletions doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@ Core Lightning Documentation
showrunes <showrunes.7.md>
signinvoice <signinvoice.7.md>
signmessage <signmessage.7.md>
signmessagewithkey <signmessagewithkey.7.md>
signpsbt <signpsbt.7.md>
splice_init <splice_init.7.md>
splice_signed <splice_signed.7.md>
Expand Down
6 changes: 3 additions & 3 deletions doc/lightning-cli.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ this is to avoid having lightningd interpret the position of an argument.

Arguments may be integer numbers (composed entirely of digits), floating-point
numbers (has a radix point but otherwise composed of digits), *true*, *false*,
or *null*. Arguments which begin with *{*, *[* or *"* are also considered
or *null*. Arguments which begin with *`{`*, *`[`* or *`"`* are also considered
raw JSON and are passed through. Other arguments are treated as strings.

Some commands have optional arguments. You may use *null* to skip
Expand Down Expand Up @@ -147,12 +147,12 @@ If the command succeeds, the exit status is 0. Otherwise:
AUTHOR
------

Rusty Russell <<[email protected]>> is mainly to blame.
Rusty Russell [[email protected]](mailto:[email protected]) is mainly to blame.

RESOURCES
---------

Main web site: <https://github.com/ElementsProject/lightning>
Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)

COPYING
-------
Expand Down
6 changes: 3 additions & 3 deletions doc/lightning-downgrade.8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ to gain our eternal gratitude!
AUTHOR
------

Rusty Russell <<[email protected]>> wrote the initial version of **lightning-downgrade** and this man page.
Rusty Russell [[email protected]](mailto:[email protected]) wrote the initial version of **lightning-downgrade** and this man page.

SEE ALSO
--------
Expand All @@ -92,11 +92,11 @@ lightningd(8), lightningd-config(5)
RESOURCES
---------

Main web site: <https://github.com/ElementsProject/lightning>
Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)

COPYING
-------

Note: the modules in the ccan/ directory have their own licenses, but
the rest of the code is covered by the BSD-style MIT license.
Main web site: <https://github.com/ElementsProject/lightning>
Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)
9 changes: 4 additions & 5 deletions doc/lightning-hsmtool.8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,8 @@ to gain our eternal gratitude!
AUTHOR
------

ZmnSCPxj <<[email protected]>> wrote the initial version of
this man page, but many others did the hard work of actually implementing
**lightning-hsmtool**.
ZmnSCPxj [[email protected]](mailto:[email protected]) wrote the initial version of
this man page, but many others did the hard work of actually implementing **lightning-hsmtool**.

SEE ALSO
--------
Expand All @@ -118,11 +117,11 @@ lightningd(8), lightningd-config(5)
RESOURCES
---------

Main web site: <https://github.com/ElementsProject/lightning>
Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)

COPYING
-------

Note: the modules in the ccan/ directory have their own licenses, but
the rest of the code is covered by the BSD-style MIT license.
Main web site: <https://github.com/ElementsProject/lightning>
Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)
11 changes: 5 additions & 6 deletions doc/lightning-reckless.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ invoked, so **python3** should be available in your environment. This
can be verified with **which Python3**. The default reckless directory
is $USER/.lightning/reckless and it should be possible for the
lightningd user to execute files located here. If this is a problem,
the option flag **reckless -d=<my\_alternate\_dir>** may be used to
the option flag **reckless -d=`my_alternate_dir`** may be used to
relocate the reckless directory from its default. Consider creating a
permanent alias in this case.

Expand Down Expand Up @@ -145,16 +145,15 @@ based.

Rusty Russell wrote the outline for the reckless utility's function

Alex Myers <<[email protected]>> is mostly responsible for the
reckless code and this man page, with thanks to Christian Decker for
extensive review.
Alex Myers [[email protected]](mailto:[email protected]) is mostly responsible for the
reckless code and this man page, with thanks to Christian Decker for extensive review.

SEE ALSO
--------

reckless(7), Core-Lightning plugins repo: <https://github.com/lightningd/plugins>
reckless(7), Core-Lightning plugins repo: [https://github.com/lightningd/plugins](https://github.com/lightningd/plugins)

RESOURCES
---------

Main web site: <https://github.com/ElementsProject/lightning>
Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)
Loading
Loading