python: auto-generate OPTIONS.rst

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

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

python/docs/OPTIONS.rst

@@ -1,14 +1,30 @@
-Commandline options for trezorctl
+Command-line options for trezorctl
-=================================
+==================================
 
 See `EXAMPLES.rst <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 <command> --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.
+    binance          Binance Chain commands.
-    cardano-get-address             Get Cardano address.
+    btc              Bitcoin and Bitcoin-like coins commands.
-    cardano-get-public-key          Get Cardano public key.
+    cardano          Cardano commands.
-    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             CoSi (Cothority / collective signing) commands.
-    cosi-sign                       Ask device to sign using CoSi.
+    crypto           Miscellaneous cryptography features.
-    decrypt-keyvalue                Decrypt value by given key and path.
+    device           Device management commands - setup, recover seed, wipe, etc.
-    disable-passphrase              Disable passphrase.
+    eos              EOS commands.
-    enable-passphrase               Enable passphrase.
+    ethereum         Ethereum commands.
-    encrypt-keyvalue                Encrypt value by given key and path.
+    fido             FIDO2, U2F and WebAuthN management commands.
-    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             Lisk commands.
-    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           Monero commands.
-    monero-get-address              Get Monero address for specified path.
+    nem              NEM commands.
-    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.
+    ripple           Ripple commands.
-    reset-device                    Perform device setup and generate new seed.
+    set              Device settings.
-    ripple-get-address              Get Ripple address
+    stellar          Stellar commands.
-    ripple-sign-tx                  Sign Ripple transaction
+    tezos            Tezos commands.
-    sd-protect                      Secure the device with SD card protection.
+    usb-reset        Perform USB reset on stuck devices.
-    self-test                       Perform a self-test.
+    version          Show version of trezorctl/trezorlib.
-    set-auto-lock-delay             Set auto-lock delay (in seconds).
+
-    set-flags                       Set device flags.
+Binance Chain commands.
-    set-homescreen                  Set new homescreen.
+~~~~~~~~~~~~~~~~~~~~~~~
-    set-label                       Set new device label.
+
-    set-passphrase-source           Set passphrase source.
+.. code::
-    set-u2f-counter                 Set U2F counter.
+
+  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.
-    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.
+Cardano commands.
-    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.
+.. 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.
+

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))

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'