Page MenuHomePhabricator

Format generated RPC docs with code blocks in the Results sections.
AbandonedPublic

Authored by jasonbcox on Aug 12 2020, 23:44.

Details

Reviewers
deadalnix
Group Reviewers
Restricted Project
Summary

The Results section(s) in RPC help text tend to be JSON-like
and are best formatted in code blocks when rendered on the website.

There are some trade-offs for this and related approaches:

  1. Insert code blocks based on string search of known headings on RPC output Pros:
    • Lowest ownership cost
    • Good separation of concerns Cons:
    • Not robust to changes in RPC headings, however these are not expected to change often.
    • Specific to the Results sections
  2. Insert code blocks in ToDescriptionString() in the node software Pros:
    • Best correctness, since boundaries between parts of the help text are well defined at this stage Cons:
    • Poor separation of concerns. The node software should not care how RPC help text is rendered beyond the terminal.
    • Markdown could be introduced as a format specified via runtime argument to alleviate the above, but this introduces additional maintenance overhead in the node software which is strictly worse than having this overhead elsewhere.
    • If Markdown were adopted as the only format, this approach still suffers from degraded usage of vertical screen space.
  3. Insert code blocks based on string search of JSON-like structures on RPC output Pros:
    • Improved rendering of all JSON-like content (not just the Results sections) Cons:
    • Difficult to implement correctly. A high number of false positives and negatives would be expected, resulting in low-quality RPC documentation.
    • In order to reduce false-positives/negatives, the parsing would need to be aware of most/all Markdown rules.

Given the above, I think option #1 is the most reasonable, so I have implemented it in this patch.

Test Plan

build-configurations.py build-docs
Verify <build>/doc/rpc/... files contain code blocks where expected.

Diff Detail

Repository
rABC Bitcoin ABC
Branch
rpc-doc-codeblocks
Lint
Lint Passed
Unit
No Test Coverage
Build Status
Buildable 12385
Build 24949: Build Diffbuild-diff · build-without-wallet · build-clang-10 · build-clang-tidy
Build 24948: arc lint + arc unit

Event Timeline

jasonbcox planned changes to this revision.

Simplified and made the implementation more robust to certain edge cases.

deadalnix requested changes to this revision.Aug 15 2020, 12:43
deadalnix added a subscriber: deadalnix.

You need to stop butchering this generate.go thing.

It looks like evrybody is able to generate nice looking doc from that.

https://bitcoincore.org/en/doc/0.20.0/rpc/util/deriveaddresses/
https://docs.bitcoincashnode.org/doc/json-rpc/getblockchaininfo/
https://developer.bitcoin.org/reference/rpc/index.html

So now is the time to stop yack shaving and actually get things going.

This revision now requires changes to proceed.Aug 15 2020, 12:43