IPC docs (for v31)#1250
Draft
Sjors wants to merge 5 commits into
Draft
Conversation
Pure refactor: no behavior change. Splits the RPC-specific code (BITCOIN_*, Command/Group, getVersion, generateRPC, run) out of generate.go into rpc.go, leaving generate.go as a thin entry point. Adds a go.mod so multi-file builds work with `go run .`.
Adds a CI job that installs Go and Cap'n Proto on Debian and runs `go vet` and `go build` against contrib/doc-gen so syntax regressions in the generator are caught on every PR. Full RPC/IPC docs regeneration still requires a running bitcoind plus a matching Bitcoin Core source checkout, which is out of scope for CI.
Adds generation of HTML reference docs for Bitcoin Core's Cap'n Proto
IPC (libmultiprocess) interfaces. The new ipc.go module shells out
to `capnp` for canonical schema text, parses interfaces and structs,
and emits, per Bitcoin Core version >= 31:
* one HTML page per IPC method
* a per-interface index (linked from `make<Iface>` factories)
* a single Cap'n Proto structs page with anchors per struct
* a per-version IPC index and a site-wide IPC landing page
Polish:
- methods named `construct` and deprecated `*Old<n>` are hidden
- long signatures are reformatted with one parameter per line
- factory methods like `makeMining` link to the interface they
return
- sidebar groups render in 'init first / structs last / others
alpha' order so the entry point and reference bookend the
method groups
The site layout (_layouts/doc.html) and navigation
(_includes/navigation.html) gain an 'IPC Docs' branch parallel to
the existing RPC docs branch and gate IPC content with an
experimental-API warning banner.
Extends the IPC generator to read C++ doxygen-style comments out of
src/interfaces/{init,echo,mining}.h and attach them to the matching
methods on each Cap'n Proto interface. The renderer understands the
common @param[in/out], @RetVal and @returns/@return tags and emits a
`<dl class="ipc-doc-tags">` definition list for them; free prose is
emitted as paragraphs.
Also linkifies whole-word occurrences of known interface and struct
names in the rendered description so e.g. `@retval BlockTemplate`
points at the BlockTemplate interface page.
Adds an interfaceHeaders map mapping each Cap'n Proto interface to a
header file (or to "" to opt out of doxygen). Adding a new interface
to the schemas without an entry in the map is now a hard error, so we
do not silently miss documenting it.
Adds the generated Cap'n Proto IPC reference for Bitcoin Core v31.0, produced by contrib/doc-gen against github.com/bitcoin/bitcoin tag v31.0 (commit 6574cb4086).
Member
Author
|
@ryanofsky I wonder if it makes sense to first work on automatically copying |
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.
This adds IPC documentation, starting with v31.0.
This adds about 1000 (LLM generated) lines to the generator, which I need to study a bit more. Mainly looking for feedback on the layout and contents now.
Fixes #1247