Render structured RPC docs from OpenRPC specs#1267
Open
satsfy wants to merge 6 commits into
Open
Conversation
Add one OpenRPC document per release under contrib/doc-gen/openrpc-specs/, covering 26.0 through 31.0 and the maintained patch releases. These are fallbacks for the doc generator: released nodes do not have the getopenrpcinfo RPC yet, so the documents were produced by cherry-picking it onto each release tag and dumping from the node. Once getopenrpcinfo ships in a release, the generator takes the document from the running node directly. The directory README records the provenance in detail.
Keep the existing bitcoin-cli flow: the script still runs against a regtest node and the classic plain-text pages are still produced from `bitcoin-cli help` output. On top of that, render a structured page (synopsis, arguments table, result schema tree, examples) and a raw OpenRPC JSON page for every method, behind a toggle. The OpenRPC document comes from the node's getopenrpcinfo when available; for releases that predate that RPC the committed documents under contrib/doc-gen/openrpc-specs/ are used as a fallback. When neither source exists the script produces the classic pages only, as before.
Add the doc layout branch that renders the three views with a toggle to switch between them, along with the styles for the structured page. The structured view lays out the synopsis, the arguments table, and the result schema as a nested tree with typed tokens and per-level guides. The styles also keep the RPC column clear of the container edges on narrow screens.
Add the RPC pages produced by contrib/doc-gen from the committed specs. Each documented method has a structured page, a plain-text page, and an OpenRPC JSON page.
Add an editor-style fold toggle to every row of the structured result tree that has children. A small script inserts the toggle at load time, so the generated pages themselves are unchanged; collapsing hides the row's nested list. Rows without children are left as they are.
A small script wraps each box in a positioned host and adds a copy-to-clipboard button at its top right, using the Font Awesome icons the site already ships. The button sits outside the scrolling element, so it stays in place, and its solid background keeps it readable where it overlaps a long first line.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Forward note: the diff is big but most of it is auto-generated json and html files, pls read commit by commit to review.
The RPC reference pages are a plaintext dump of
bitcoin-cli helptoday. This reworks contrib/doc-gen to read committed OpenRPC specs and render structured pages with an arguments table and a typed result tree. Every element in the tree, aside from root, is collapsible.A recent Open PR in Bitcoin Core introduces OpenRPC spec schema for all RPCs of Bitcoin Core using core's own documentation. I have backported it to applicable version of Bitcoin Core (v31 - v26) and generated OpenRPC schemas with
bitcoin-cli getopenrpcinfoon each, producing JSON files. Further backports from v25 required workarounds that caused the output to become progressively more unsafe, so earlier versions keep only the current plaintext rendering.The old plain-text format from help stays available in the UI, just one click away, as well as the OpenRPC spec. Each RPC method URI has a companion plain-text page at
.../<name>/raw/and.../<name>/openrpc/, reached from a toggle next to the title. The switch UI element is reactive to screen size, assuming a separate row when less space is available.The field "examples" is not exported in openrpc, so I take them from the existing plaintext spec. The same can be said for
named-argumentsannotations.Additionally, I added a copy button to the OpenRPC and Plain Text textboxes. Just felt like it should be there.
Note on maintenance: while
getopenrpcinfoRPC is not merged in Bitcoin Core, the process of generating a new spec will have to be manual (and I volunteer to do it in the meantime). When it is available, I can leverage the documentation directly using thecontrib/doc-gen/generate.gonode on regtest.This PR was created using Claude Opus 4.8 and reviewed by me.
It's my first time contributing here so, if I'm missing something important, please let me know.
EDIT: all the pictures I had taken on this PR intially was using a dark mode extension, so they were dark. I didn't actually implement dark mode. Edit updates the pictures.