Improve / simplify documentation

README.rst

@@ -7,7 +7,7 @@ python-trezor
 .. image:: https://badges.gitter.im/trezor/community.svg
     :target: https://gitter.im/trezor/community
 
-Python library for communicating with TREZOR Hardware Wallet
+Python library and commandline client for communicating with TREZOR Hardware Wallet
 
 See https://trezor.io for more information
 
@@ -41,67 +41,21 @@ or build via ports:
   cd /usr/ports/security/py-trezor
   make install clean
 
-Usage
------
 
-There is a command line tool called ``trezorctl`` which can perform various tasks. Use the following to learn about its commands:
+Commandline client (trezorctl)
+---------------------------
 
-.. code::
+The included ``trezorctl`` python script can perform various tasks such as changing setting in the Trezor, signing transactions, retrieving account info and addresses. See the `docs/ <docs/>`_ sub folder for detailed examples and options.
 
-  trezorctl --help
+NOTE: An older version of the ``trezorctl`` command is `available for Debian Stretch <https://packages.debian.org/en/stretch/python-trezor>`_ (and comes pre-installed on `Tails OS <https://tails.boum.org/>`_).
 
-or to learn options of a particular command:
 
-.. code::
+Python Library
+--------------
 
-  trezorctl commands --help
+You can use this python library to interact with a Bitcoin Trezor and use its capabilities in your application.
+See examples here in the `tools/ <tools/>`_ sub folder.
 
-or visit `docs/USAGE.rst <docs/USAGE.rst>`_ page for more info.
-
-NOTE: The ``trezorctl`` command is `available for Debian Stretch <https://packages.debian.org/en/stretch/python-trezor>`_ (and comes pre-installed on `Tails OS <https://tails.boum.org/>`_).
-
-To use the library in your application look at the following example.
-
-Example
--------
-
-also found in ``tools/helloworld.py``
-
-.. code:: python
-
-  #!/usr/bin/env python
-
-  from trezorlib.client import TrezorClient
-  from trezorlib.transport_hid import HidTransport
-
-  def main():
-      # List all connected TREZORs on USB
-      devices = HidTransport.enumerate()
-
-      # Check whether we found any
-      if len(devices) == 0:
-          print('No TREZOR found')
-          return
-
-      # Use first connected device
-      transport = HidTransport(devices[0])
-
-      # Creates object for manipulating TREZOR
-      client = TrezorClient(transport)
-
-      # Print out TREZOR's features and settings
-      print(client.features)
-
-      # Get the first address of first BIP44 account
-      # (should be the same address as shown in wallet.trezor.io)
-      bip32_path = client.expand_path("44'/0'/0'/0/0")
-      address = client.get_address('Bitcoin', bip32_path)
-      print('Bitcoin address:', address)
-
-      client.close()
-
-  if __name__ == '__main__':
-      main()
 
 PIN Entering
 ------------

docs/EXAMPLES.rst

@@ -1,7 +1,7 @@
-Usage
+Examples demonstrating how to use trezorctl
-=====
+===========================================
 
-Show help for all command:
+Show all available `options <OPTIONS.rst>`_:
 
 .. code::
 
@@ -15,8 +15,8 @@ Retrieve features, settings and coin types supported by your device:
   trezorctl get_features
 
 
-Bitcoin
+Bitcoin examples
--------
+----------------
 
 Get first receiving address of first account for Bitcoin (Legacy / non-SegWit):
 
@@ -97,8 +97,8 @@ The signed transaction text can then be inspected in Electrum (`screenshot <sign
 The final broadcast and mined transaction can be seen here: https://blockchain.info/tx/270684c14be85efec9adafa50339fd120658381ed2300b9207d0a0df2a5f0bf9
 
 
-Litecoin
+Litecoin examples
---------
+-----------------
 
 Get first receiving address of first account for Litecoin (Bech32 native SegWit P2WPKH):
 
@@ -114,7 +114,7 @@ Get first receiving address of first account for Litecoin (SegWit-in-P2SH):
   trezorctl get_address --coin Litecoin --script-type p2shsegwit --address "m/49'/2'/0'/0/0"
 
 
-NOTES
+Notes
 -----
 
-1. Bech32 native SegWit encoded addresses require Trezor Firmware v1.6.0 or later.
+1. Bech32 native SegWit encoded addresses require `Trezor Firmware v1.6.0 <https://github.com/trezor/trezor-mcu/releases>`_ or later.

docs/OPTIONS.rst

@@ -0,0 +1,63 @@
+Commandline options for trezorctl
+=================================
+
+See `EXAMPLES.rst <EXAMPLES.rst>`_ for examples on how to use.
+
+Use the following command to see all options:
+
+.. code::
+
+  trezorctl --help
+
+
+.. code::
+
+  Usage: trezorctl [OPTIONS] COMMAND [ARGS]...
+
+  Options:
+    -t, --transport [usb|udp|pipe|bridge]
+                                    Select transport used for communication.
+    -p, --path TEXT                 Select device by transport-specific path.
+    -v, --verbose                   Show communication messages.
+    -j, --json                      Print result as JSON object
+    --help                          Show this message and exit.
+
+  Commands:
+    backup_device            Perform device seed backup.
+    change_pin               Change new PIN or remove existing.
+    clear_session            Clear session (remove cached PIN, passphrase,...
+    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.
+    decrypt_message          Decrypt message.
+    disable_passphrase       Disable passphrase.
+    enable_passphrase        Enable passphrase.
+    encrypt_keyvalue         Encrypt value by given key and path.
+    encrypt_message          Encrypt message.
+    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...
+    ethereum_verify_message  Verify message signed with Ethereum address.
+    firmware_update          Upload new firmware to device (must be in...
+    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.
+    list                     List connected TREZOR devices.
+    list_coins               List all supported coin types by the device.
+    load_device              Load custom configuration to the device.
+    nem_get_address          Get NEM address for specified path.
+    nem_sign_tx              Sign (and optionally broadcast) NEM...
+    ping                     Send ping message.
+    recovery_device          Start safe recovery workflow.
+    reset_device             Perform device setup and generate new seed.
+    self_test                Perform a self-test.
+    set_flags                Set device flags.
+    set_homescreen           Set new homescreen.
+    set_label                Set new device label.
+    set_u2f_counter          Set U2F counter.
+    sign_message             Sign message using address of given path.
+    sign_tx                  Sign transaction.
+    verify_message           Verify message.
+    version                  Show version of trezorctl/trezorlib.
+    wipe_device              Reset device to factory defaults and remove...

docs/README.rst

@@ -0,0 +1,5 @@
+Documentation for trezorctl commandline client
+==============================================
+
+* `EXAMPLES.rst <EXAMPLES.rst>`_ - Examples demonstrating how to use trezorctl 
+* `OPTIONS.rst <OPTIONS.rst>`_ - Commandline options for trezorctl