def split_description(self, full_description):
if "summary" in self.annotation:
summary = self.annotation["summary"]
description = full_description
elif self.help_data["description"]:
summary = uncapitalize(full_description.partition(".")[0]) + "."
description = full_description[len(summary) + 1:].lstrip()
else:
summary = "does %s." % display_name(self.command)
description = None
return summary, description
def split_description(self, full_description):
if "summary" in self.annotation:
summary = self.annotation["summary"]
description = full_description
elif full_description:
if "." in full_description:
summary = uncapitalize(
full_description.partition(".")[0]) + "."
description = full_description[len(summary) + 1:].lstrip()
else:
summary = uncapitalize(full_description.rstrip()) + "."
description = ""
summary = " ".join(summary.splitlines())
else:
summary = "does %s." % display_name(self.command)
description = None
return summary, description
def add_see_also_command(self, page, command):
name = display_name(command)
lower_name = uncapitalize(name)
page.text("* [%s][rpc %s]: {{summary_%s}}" %
(name, command, lower_name))
def render_overview_page(self, all_commands, render_version_info=True):
with open(self.output_dir / "quick-reference.md", "w") as file:
page = Page()
self.add_license_header(page)
page.tag(
"assign",
'filename="_data/devdocs/en/bitcoin-core/rpcs/quick-reference.md"'
)
page.nl()
page.text("#### Quick Reference {#rpc-quick-reference}")
page.tag("include", "helpers/subhead-links.md")
page.nl()
if render_version_info:
self.render_version_info(page)
page.text(
"""<!-- the summaries used below are defined in the files for the
particular RPC and aggregated into this helper file by the makefile
function manual-update-summaries-file. For example, to edit the
summary for GetBestBlockHash, edit
_includes/rpc/getbestblockhash.md and run `make manual-update-summaries`. -->"""
)
page.tag("include", "helpers/summaries.md")
page.nl()
for category in all_commands:
page.text("#### " + category + " RPCs")
page.text("{:.no_toc}")
page.text("<!-- no subhead-links here -->\n")
with page.tag("autocrossref"):
page.nl()
if category == "Wallet":
page.text(
"""**Note:** the wallet RPCs are only available if Bitcoin Core was built
with [wallet support][]{:#term-wallet-support}{:.term}, which is the
default.
""")
for command in all_commands[category]:
cmd = command.split(" ")[0]
item = "* [" + display_name(cmd) + "]"
item += "[rpc " + cmd + "]: "
item += "{{summary_" + uncapitalize(display_name(cmd))
if cmd == "ping":
item += "-rpc"
item += "}}"
if render_version_info:
annotation = self.annotations.annotation(cmd)
if "added" in annotation:
item += " {{NEW%s}}" % annotation[
"added"].replace(".", "_")
if "added" in annotation and "changed" in annotation:
item += ","
if "changed" in annotation:
item += " {{UPDATED%s}}" % annotation[
"changed"].replace(".", "_")
if "deprecated" in annotation:
item += " {{DEPRECATED}}"
page.text(item)
page.nl()
page.nl()
file.write(page.out)
def process_command_help(self, help_data):
self.help_data = help_data
# print(help_data)
self.command = help_data["command"].split(" ")[0]
self.annotation = self.annotations.annotation(self.command)
page = Page()
self.add_license_header(page)
name = display_name(self.command)
lower_name = name[0].lower() + name[1:]
page.tag(
"assign",
'filename="_data/devdocs/en/bitcoin-core/rpcs/rpcs/%s.md"' %
self.command)
title = "\n##### %s" % name
if self.command == "ping":
title += " {#ping-rpc}"
suffix = "-rpc"
else:
suffix = ""
page.text(title)
page.tag("include", "helpers/subhead-links.md")
page.nl()
summary, description = self.split_description(help_data["description"])
page.tag("assign", 'summary_%s%s="%s"' % (lower_name, suffix, summary))
page.nl()
with page.tag("autocrossref"):
page.nl()
self.add_version_note(page)
self.add_wallet_note(page)
page.text("The `%s` RPC {{summary_%s%s}}\n" %
(self.command, lower_name, suffix))
if description:
quoted = False
for line in description.splitlines():
if line.startswith(" "):
if not quoted:
page.text("{% endautocrossref %}")
page.nl()
quoted = True
elif quoted:
page.nl()
page.text("{% autocrossref %}")
quoted = False
page.text(line)
if quoted:
page.nl()
page.text("{% autocrossref %}")
page.nl()
if "arguments" in help_data:
if not help_data["arguments"]:
page.text("*Parameters: none*\n")
else:
count = 1
for arg in help_data["arguments"]:
page.text("*Parameter #%s---%s*\n" %
(count, self.arg_summary(arg)))
with page.tag("itemplate", "ntpd1"):
page.text('- n: "%s"' % self.arg_n(arg))
page.text(' t: "%s"' % self.arg_t(arg))
page.text(' p: "%s"' %
self.yaml_escape(self.arg_p(arg)))
page.text(' d: "%s"' %
self.yaml_escape(self.arg_d(arg)))
page.nl()
page.nl()
if "literal_description" in arg:
page.text(
self.guarded_code_block(
arg["literal_description"]))
count += 1
if help_data["results"] == [{
'title_extension': ''
}] or help_data["results"] == []:
page.text(self.result_null())
else:
for result in help_data["results"]:
result_header = "*Result"
if "title_extension" in result and result[
"title_extension"]:
result_header += "---" + \
result["title_extension"].lstrip()
result_header += "*\n"
page.text(result_header)
if result["format"] == "literal":
page.text(self.guarded_code_block(result["text"]))
else:
with page.tag("itemplate", "ntpd1"):
page.text('- n: "%s"' % "`result`")
page.text(' t: "%s"' % self.result_t(result))
page.text(' p: "Required<br>(exactly 1)"')
page.text(' d: "%s"' %
self.yaml_escape(result["description"]))
page.nl()
page.nl()
if help_data["examples"]:
page.text("*Example*\n")
for example in help_data["examples"]:
if example.startswith("> "):
if not example.startswith("> curl"):
with page.tag("highlight", "bash"):
page.text(example[2:].rstrip())
else:
if (not example.startswith("As json rpc")
and not example.startswith("As a json rpc")
and not example.startswith("As a JSON-RPC")):
page.text(example)
page.nl()
page.nl()
self.add_see_also(page)
return page.out
def update_config(self, commands):
self.update_file(
commands, Path("_config.yml"), ' "RPCs":', lambda command:
(" - '%s': \"/en/developer-reference#%s\"" %
(display_name(command), self.anchor(command))))
def render_overview_page(self, all_commands):
with open(self.output_dir / "quick-reference.md", "w") as file:
page = Page()
self.add_license_header(page)
page.tag(
"assign",
'filename="_data/devdocs/en/bitcoin-core/rpcs/quick-reference.md"'
)
page.nl()
page.text("#### Quick Reference {#rpc-quick-reference}")
page.tag("include", "helpers/subhead-links.md")
page.nl()
with page.tag("comment"):
page.text(
"""Styling notes: use highly-visible style for upcoming changes (not yet
released) and changes made in the last 6 months. Use less-visible
style for changes made up to two years ago. Don't point out
changes made more than two years ago.
Use v0.n.n in abbreviation title to prevent autocrossrefing.""")
page.nl()
page.text("<!-- Deprecated -->")
page.tag(
"assign",
"DEPRECATED='**<abbr title=\"Deprecated; will be removed in a future version of Bitcoin Core\">Deprecated</abbr>**'"
)
self.add_version_helpers(page, "0.14.1", "April 2017", bold=True)
self.add_version_helpers(page,
"0.14.0",
"March 2017",
new=True,
bold=True)
self.add_version_helpers(page, "0.13.1", "September 2016")
self.add_version_helpers(page, "0.13.0", "August 2016", new=True)
self.add_version_helpers(page, "0.12.1", "April 2016")
self.add_version_helpers(page, "0.12.0", "February 2016", new=True)
self.add_version_helpers(page,
"0.11.0",
"July 2015",
new=True,
updated=False)
page.text(
"""<!-- the summaries used below are defined in the files for the
particular RPC and aggregated into this helper file by the makefile
function manual-update-summaries-file. For example, to edit the
summary for GetBestBlockHash, edit
_includes/rpc/getbestblockhash.md and run `make manual-update-summaries`. -->"""
)
page.tag("include", "helpers/summaries.md")
page.nl()
for category in all_commands:
page.text("#### " + category + " RPCs")
page.text("{:.no_toc}")
page.text("<!-- no subhead-links here -->\n")
with page.tag("autocrossref"):
page.nl()
if category == "Wallet":
page.text(
"""**Note:** the wallet RPCs are only available if Bitcoin Core was built
with [wallet support][]{:#term-wallet-support}{:.term}, which is the
default.
""")
for command in all_commands[category]:
cmd = command.split(" ")[0]
item = "* [" + display_name(cmd) + "]"
item += "[rpc " + cmd + "]: "
item += "{{summary_" + \
uncapitalize(display_name(cmd)) + "}}"
annotation = self.annotations.annotation(cmd)
if "added" in annotation:
item += " {{NEW%s}}" % annotation["added"].replace(
".", "_")
if "added" in annotation and "changed" in annotation:
item += ","
if "changed" in annotation:
item += " {{UPDATED%s}}" % annotation[
"changed"].replace(".", "_")
if "deprecated" in annotation:
item += " {{DEPRECATED}}"
page.text(item)
page.nl()
page.nl()
file.write(page.out)
def test_display_name():
assert display_name("abandontransaction") == "AbandonTransaction"
assert display_name("addmultisigaddress") == "AddMultiSigAddress"
assert display_name("addnode") == "AddNode"
assert display_name("disconnectnode") == "DisconnectNode"
assert display_name("listsinceblock") == "ListSinceBlock"
assert display_name("listwallets") == "ListWallets"
assert display_name("setban") == "SetBan"
assert display_name("signmessagewithprivkey") == "SignMessageWithPrivKey"
assert display_name("listaccounts") == "ListAccounts"
assert display_name("listtransactions") == "ListTransactions"
assert display_name("listwallets") == "ListWallets"
assert display_name("getaddressesbyaccount") == "GetAddressesByAccount"
assert display_name("submitheader") == "SubmitHeader"
assert display_name("getnodeaddresses") == "GetNodeAddresses"
assert display_name("joinpsbts") == "JoinPsbts"
assert display_name("utxoupdatepsbt") == "UtxoUpdatePsbt"
assert display_name("deriveaddresses") == "DeriveAddresses"
assert display_name("setlabel") == "SetLabel"
assert display_name("listlabels") == "ListLabels"
def test_display_name():
assert display_name("abandontransaction") == "AbandonTransaction"
assert display_name("addmultisigaddress") == "AddMultiSigAddress"
assert display_name("addnode") == "AddNode"
assert display_name("disconnectnode") == "DisconnectNode"
assert display_name("listsinceblock") == "ListSinceBlock"
assert display_name("listwallets") == "ListWallets"
assert display_name("setban") == "SetBan"
assert display_name("signmessagewithprivkey") == "SignMessageWithPrivKey"
assert display_name("listaccounts") == "ListAccounts"
assert display_name("listtransactions") == "ListTransactions"
assert display_name("listwallets") == "ListWallets"
assert display_name("getaddressesbyaccount") == "GetAddressesByAccount"