From b6d46e93e1b8f1324044d04171945e4624a4da84 Mon Sep 17 00:00:00 2001 From: matejcik Date: Fri, 15 Nov 2019 13:26:24 +0100 Subject: [PATCH] python: auto-generate OPTIONS.rst --- python/CHANGELOG.md | 2 + python/Makefile | 6 +- python/docs/OPTIONS.rst | 457 ++++++++++++++++++---- python/helper-scripts/make-options-rst.py | 53 +++ python/src/trezorlib/cli/stellar.py | 4 +- 5 files changed, 449 insertions(+), 73 deletions(-) create mode 100755 python/helper-scripts/make-options-rst.py diff --git a/python/CHANGELOG.md b/python/CHANGELOG.md index 8ecf8275e..c74b9595e 100644 --- a/python/CHANGELOG.md +++ b/python/CHANGELOG.md @@ -11,6 +11,7 @@ _At the moment, the project does **not** adhere to [Semantic Versioning](https:/ ### Changed +- `trezorctl` command was reworked for ease of use and maintenance. See `trezorctl --help` and `OPTIONS.rst` for details. [f#510] - updated EOS transaction parser to match `cleos` in `delegatebw` and `undelegatebw` actions [f#680] [f#681] ## [0.11.5] - 2019-09-26 @@ -336,6 +337,7 @@ _At the moment, the project does **not** adhere to [Semantic Versioning](https:/ [f#411]: https://github.com/trezor/trezor-firmware/issues/411 [f#420]: https://github.com/trezor/trezor-firmware/issues/420 [f#445]: https://github.com/trezor/trezor-firmware/issues/445 +[f#510]: https://github.com/trezor/trezor-firmware/issues/510 [f#525]: https://github.com/trezor/trezor-firmware/issues/525 [f#680]: https://github.com/trezor/trezor-firmware/issues/680 [f#681]: https://github.com/trezor/trezor-firmware/issues/681 diff --git a/python/Makefile b/python/Makefile index 5960a4110..13dc39962 100644 --- a/python/Makefile +++ b/python/Makefile @@ -26,10 +26,14 @@ build: install: $(SETUP) install -dist: clean +dist: clean doc $(SETUP) sdist $(SETUP) bdist_wheel +doc: + $(PYTHON) helper-scripts/linkify-changelog.py + $(PYTHON) helper-scripts/make-options-rst.py + clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts clean-build: ## remove build artifacts diff --git a/python/docs/OPTIONS.rst b/python/docs/OPTIONS.rst index cb3a4dfd1..67e44f44c 100644 --- a/python/docs/OPTIONS.rst +++ b/python/docs/OPTIONS.rst @@ -1,14 +1,30 @@ -Commandline options for trezorctl -================================= +Command-line options for trezorctl +================================== See `EXAMPLES.rst `_ for examples on how to use. -Use the following command to see all options: +``trezorctl`` is split into a number of subcommands based on currency and/or +functionality. The best way to get up-to-date help is to use the integrated help option. + +The full list of subcommands can be seen like so: .. code:: trezorctl --help +Each subcommand has its own help, shown with ``trezorctl --help``. + +In addition, aliases are available for currency ticker symbols. For example, instead +of ``trezorctl btc sign-message``, it is possible to use ``trezorctl ltc sign-message``. +In that case, the ``-c`` option of ``sign-message`` can be omitted. + +List of subcommands +------------------- + +For convenience of search, the help texts of all commands and subcommands are listed +on one page here. + +.. ### ALL CONTENT BELOW IS GENERATED BY helper-scripts/make-options-rst.py ### .. code:: Usage: trezorctl [OPTIONS] COMMAND [ARGS]... @@ -17,73 +33,374 @@ Use the following command to see all options: -p, --path TEXT Select device by specific path. -v, --verbose Show communication messages. -j, --json Print result as JSON object + --version Show the version and exit. --help Show this message and exit. Commands: - backup-device Perform device seed backup. - cardano-get-address Get Cardano address. - cardano-get-public-key Get Cardano public key. - cardano-sign-tx Sign Cardano transaction. - change-pin Set, change or remove PIN. - clear-session Clear session (remove cached PIN, passphrase, etc.). - cosi-commit Ask device to commit to CoSi signing. - cosi-sign Ask device to sign using CoSi. - decrypt-keyvalue Decrypt value by given key and path. - disable-passphrase Disable passphrase. - enable-passphrase Enable passphrase. - encrypt-keyvalue Encrypt value by given key and path. - eos_get_public_key Get EOS public key in base58 encoding. - eos_sign_transaction Sign EOS transaction... - ethereum-get-address Get Ethereum address in hex encoding. - ethereum-sign-message Sign message with Ethereum address. - ethereum-sign-tx Sign (and optionally publish) Ethereum transaction. - ethereum-verify-message Verify message signed with Ethereum address. - firmware-update Upload new firmware to device. - get-address Get address for specified path. - get-entropy Get example entropy. - get-features Retrieve device features and settings. - get-public-node Get public node of given path. - lisk-get-address Get Lisk address for specified path. - lisk-get-public-key Get Lisk public key for specified path. - lisk-sign-message Sign message with Lisk address. - lisk-sign-tx Sign Lisk transaction. - lisk-verify-message Verify message signed with Lisk address. - list List connected Trezor devices. - load-device Load custom configuration to the device. - monero-get-address Get Monero address for specified path. - monero-get-watch-key Get Monero watch key for specified path. - nem-get-address Get NEM address for specified path. - nem-sign-tx Sign (and optionally broadcast) NEM transaction. - ontology-get-address Get Ontology address for specified path. - ontology-get-public-key Get Ontology public key for specified path. - ontology-sign-ont-id-add-attributes - Sign Ontology ONT ID Attributes adding. - ontology-sign-ont-id-register Sign Ontology ONT ID Registration. - ontology-sign-transfer Sign Ontology transfer. - ontology-sign-withdraw-ong Sign Ontology withdraw Ong. - ping Send ping message. - recovery-device Start safe recovery workflow. - reset-device Perform device setup and generate new seed. - ripple-get-address Get Ripple address - ripple-sign-tx Sign Ripple transaction - sd-protect Secure the device with SD card protection. - self-test Perform a self-test. - set-auto-lock-delay Set auto-lock delay (in seconds). - set-flags Set device flags. - set-homescreen Set new homescreen. - set-label Set new device label. - set-passphrase-source Set passphrase source. - set-u2f-counter Set U2F counter. - sign-message Sign message using address of given path. - sign-tx Sign transaction. - stellar-get-address Get Stellar public address - stellar-sign-transaction Sign a base64-encoded transaction envelope - tezos-get-address Get Tezos address for specified path. - tezos-get-public-key Get Tezos public key. - tezos-sign-tx Sign Tezos transaction. - verify-message Verify message. - version Show version of trezorctl/trezorlib. - webauthn-add-credential Add the credential with the given ID as a resident credential. - webauthn-list-credentials List all resident credentials on the device. - webauthn-remove-credential Remove the resident credential at the given index. - wipe-device Reset device to factory defaults and remove all private data. + binance Binance Chain commands. + btc Bitcoin and Bitcoin-like coins commands. + cardano Cardano commands. + clear-session Clear session (remove cached PIN, passphrase, etc.). + cosi CoSi (Cothority / collective signing) commands. + crypto Miscellaneous cryptography features. + device Device management commands - setup, recover seed, wipe, etc. + eos EOS commands. + ethereum Ethereum commands. + fido FIDO2, U2F and WebAuthN management commands. + firmware-update Upload new firmware to device. + get-features Retrieve device features and settings. + lisk Lisk commands. + list List connected Trezor devices. + monero Monero commands. + nem NEM commands. + ping Send ping message. + ripple Ripple commands. + set Device settings. + stellar Stellar commands. + tezos Tezos commands. + usb-reset Perform USB reset on stuck devices. + version Show version of trezorctl/trezorlib. + +Binance Chain commands. +~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl binance --help + +.. code:: + + Usage: trezorctl binance [OPTIONS] COMMAND [ARGS]... + + Binance Chain commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Binance address for specified path. + get-public-key Get Binance public key. + sign-tx Sign Binance transaction + +Bitcoin and Bitcoin-like coins commands. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl btc --help + +.. code:: + + Usage: trezorctl btc [OPTIONS] COMMAND [ARGS]... + + Bitcoin and Bitcoin-like coins commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get address for specified path. + get-public-node Get public node of given path. + sign-message Sign message using address of given path. + sign-tx Sign transaction. + verify-message Verify message. + +Cardano commands. +~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl cardano --help + +.. code:: + + Usage: trezorctl cardano [OPTIONS] COMMAND [ARGS]... + + Cardano commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Cardano address. + get-public-key Get Cardano public key. + sign-tx Sign Cardano transaction. + +CoSi (Cothority / collective signing) commands. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl cosi --help + +.. code:: + + Usage: trezorctl cosi [OPTIONS] COMMAND [ARGS]... + + CoSi (Cothority / collective signing) commands. + + Options: + --help Show this message and exit. + + Commands: + commit Ask device to commit to CoSi signing. + sign Ask device to sign using CoSi. + +Miscellaneous cryptography features. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl crypto --help + +.. code:: + + Usage: trezorctl crypto [OPTIONS] COMMAND [ARGS]... + + Miscellaneous cryptography features. + + Options: + --help Show this message and exit. + + Commands: + decrypt-keyvalue Decrypt value by given key and path. + encrypt-keyvalue Encrypt value by given key and path. + get-entropy Get random bytes from device. + +Device management commands - setup, recover seed, wipe, etc. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl device --help + +.. code:: + + Usage: trezorctl device [OPTIONS] COMMAND [ARGS]... + + Device management commands - setup, recover seed, wipe, etc. + + Options: + --help Show this message and exit. + + Commands: + backup Perform device seed backup. + load Upload seed and custom configuration to the device. + recover Start safe recovery workflow. + sd-protect Secure the device with SD card protection. + self-test Perform a self-test. + setup Perform device setup and generate new seed. + wipe Reset device to factory defaults and remove all private data. + +EOS commands. +~~~~~~~~~~~~~ + +.. code:: + + trezorctl eos --help + +.. code:: + + Usage: trezorctl eos [OPTIONS] COMMAND [ARGS]... + + EOS commands. + + Options: + --help Show this message and exit. + + Commands: + get-public-key Get Eos public key in base58 encoding. + sign-transaction Sign EOS transaction. + +Ethereum commands. +~~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl ethereum --help + +.. code:: + + Usage: trezorctl ethereum [OPTIONS] COMMAND [ARGS]... + + Ethereum commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Ethereum address in hex encoding. + get-public-node Get Ethereum public node of given path. + sign-message Sign message with Ethereum address. + sign-tx Sign (and optionally publish) Ethereum transaction. + verify-message Verify message signed with Ethereum address. + +FIDO2, U2F and WebAuthN management commands. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl fido --help + +.. code:: + + Usage: trezorctl fido [OPTIONS] COMMAND [ARGS]... + + FIDO2, U2F and WebAuthN management commands. + + Options: + --help Show this message and exit. + + Commands: + counter Get or set the FIDO/U2F counter value. + credentials Manage FIDO2 resident credentials. + +Lisk commands. +~~~~~~~~~~~~~~ + +.. code:: + + trezorctl lisk --help + +.. code:: + + Usage: trezorctl lisk [OPTIONS] COMMAND [ARGS]... + + Lisk commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Lisk address for specified path. + get-public-key Get Lisk public key for specified path. + sign-message Sign message with Lisk address. + sign-tx Sign Lisk transaction. + verify-message Verify message signed with Lisk address. + +Monero commands. +~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl monero --help + +.. code:: + + Usage: trezorctl monero [OPTIONS] COMMAND [ARGS]... + + Monero commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Monero address for specified path. + get-watch-key Get Monero watch key for specified path. + +NEM commands. +~~~~~~~~~~~~~ + +.. code:: + + trezorctl nem --help + +.. code:: + + Usage: trezorctl nem [OPTIONS] COMMAND [ARGS]... + + NEM commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get NEM address for specified path. + sign-tx Sign (and optionally broadcast) NEM transaction. + +Ripple commands. +~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl ripple --help + +.. code:: + + Usage: trezorctl ripple [OPTIONS] COMMAND [ARGS]... + + Ripple commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Ripple address + sign-tx Sign Ripple transaction + +Device settings. +~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl set --help + +.. code:: + + Usage: trezorctl set [OPTIONS] COMMAND [ARGS]... + + Device settings. + + Options: + --help Show this message and exit. + + Commands: + auto-lock-delay Set auto-lock delay (in seconds). + display-rotation Set display rotation. + flags Set device flags. + homescreen Set new homescreen. + label Set new device label. + passphrase Enable, disable or configure passphrase protection. + pin Set, change or remove PIN. + +Stellar commands. +~~~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl stellar --help + +.. code:: + + Usage: trezorctl stellar [OPTIONS] COMMAND [ARGS]... + + Stellar commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Stellar public address. + sign-transaction Sign a base64-encoded transaction envelope. + +Tezos commands. +~~~~~~~~~~~~~~~ + +.. code:: + + trezorctl tezos --help + +.. code:: + + Usage: trezorctl tezos [OPTIONS] COMMAND [ARGS]... + + Tezos commands. + + Options: + --help Show this message and exit. + + Commands: + get-address Get Tezos address for specified path. + get-public-key Get Tezos public key. + sign-tx Sign Tezos transaction. + diff --git a/python/helper-scripts/make-options-rst.py b/python/helper-scripts/make-options-rst.py new file mode 100755 index 000000000..4536a0b13 --- /dev/null +++ b/python/helper-scripts/make-options-rst.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 + +import os + +import click + +from trezorlib.cli import trezorctl + +DELIMITER_STR = "### ALL CONTENT BELOW IS GENERATED" + +options_rst = open(os.path.dirname(__file__) + "/../docs/OPTIONS.rst", "r+") + +lead_in = [] + +for line in options_rst: + lead_in.append(line) + if DELIMITER_STR in line: + break + +options_rst.seek(0) +options_rst.truncate(0) + +for line in lead_in: + options_rst.write(line) + + +def _print(s=""): + options_rst.write(s + "\n") + + +def rst_code_block(help_str): + _print(".. code::") + _print() + for line in help_str.split("\n"): + _print((" " + line) if line else "") + _print() + + +ctx = click.Context(trezorctl.cli, info_name="trezorctl", terminal_width=99) +rst_code_block(trezorctl.cli.get_help(ctx)) + +for subcommand in sorted(trezorctl.cli.commands): + cmd = trezorctl.cli.commands[subcommand] + if not isinstance(cmd, click.Group): + continue + + heading = cmd.get_short_help_str(limit=99) + _print(heading) + _print("~" * len(heading)) + _print() + rst_code_block(f"trezorctl {subcommand} --help") + ctx = click.Context(cmd, info_name=f"trezorctl {subcommand}", terminal_width=99) + rst_code_block(cmd.get_help(ctx)) diff --git a/python/src/trezorlib/cli/stellar.py b/python/src/trezorlib/cli/stellar.py index 2fe2f9c80..6c80272be 100644 --- a/python/src/trezorlib/cli/stellar.py +++ b/python/src/trezorlib/cli/stellar.py @@ -39,7 +39,7 @@ def cli(): @click.option("-d", "--show-display", is_flag=True) @click.pass_obj def get_address(connect, address, show_display): - """Get Stellar public address""" + """Get Stellar public address.""" client = connect() address_n = tools.parse_path(address) return stellar.get_address(client, address_n, show_display) @@ -63,7 +63,7 @@ def get_address(connect, address, show_display): @click.argument("b64envelope") @click.pass_obj def sign_transaction(connect, b64envelope, address, network_passphrase): - """Sign a base64-encoded transaction envelope + """Sign a base64-encoded transaction envelope. For testnet transactions, use the following network passphrase: 'Test SDF Network ; September 2015'