Update CLI documentation

Signed-off-by: Nick Drozd <[email protected]>

bin/generate_cli_output

@@ -19,17 +19,21 @@ export PATH=$PATH:$(pwd)/../bin
 mkdir -p source/cli/output
 
 save_usage sawtooth
+
 save_usage sawtooth admin
 save_usage sawtooth admin genesis
 save_usage sawtooth admin keygen
+
 save_usage sawtooth batch
 save_usage sawtooth batch list
 save_usage sawtooth batch show
 save_usage sawtooth batch status
 save_usage sawtooth batch submit
+
 save_usage sawtooth block
 save_usage sawtooth block list
 save_usage sawtooth block show
+
 save_usage sawtooth config
 save_usage sawtooth config genesis
 save_usage sawtooth config proposal
@@ -38,35 +42,29 @@ save_usage sawtooth config proposal list
 save_usage sawtooth config proposal vote
 save_usage sawtooth config settings
 save_usage sawtooth config settings list
+
 save_usage sawtooth keygen
+
 save_usage sawtooth identity
 save_usage sawtooth identity policy
 save_usage sawtooth identity policy create
 save_usage sawtooth identity policy list
 save_usage sawtooth identity role
 save_usage sawtooth identity role create
 save_usage sawtooth identity role list
+
 save_usage sawtooth state
 save_usage sawtooth state list
 save_usage sawtooth state show
 save_usage sawtooth transaction
+
 save_usage sawtooth transaction list
 save_usage sawtooth transaction show
 
-save_usage seth
-save_usage seth init
-save_usage seth show
-save_usage seth account
-save_usage seth account import
-save_usage seth account list
-save_usage seth account create
-save_usage seth contract
-save_usage seth contract call
-save_usage seth contract create
-save_usage seth permissions
-save_usage seth permissions set
-save_usage seth-tp
-save_usage seth-rpc
+save_usage sawtooth-validator
+save_usage sawtooth-rest-api
+save_usage settings-tp
+save_usage identity-tp
 
 save_usage poet
 save_usage poet genesis
@@ -92,5 +90,17 @@ save_usage xo show
 save_usage xo take
 save_usage xo-tp-python
 
-save_usage sawtooth-validator
-save_usage sawtooth-rest-api
+save_usage seth
+save_usage seth init
+save_usage seth show
+save_usage seth account
+save_usage seth account import
+save_usage seth account list
+save_usage seth account create
+save_usage seth contract
+save_usage seth contract call
+save_usage seth contract create
+save_usage seth permissions
+save_usage seth permissions set
+save_usage seth-tp
+save_usage seth-rpc

cli/sawtooth_cli/admin.py

@@ -30,7 +30,12 @@ def do_admin(args):
 
 
 def add_admin_parser(subparsers, parent_parser):
-    parser = subparsers.add_parser('admin', parents=[parent_parser])
+    parser = subparsers.add_parser(
+        'admin',
+        help='Create validator keys and help create the genesis block',
+        description='Provides subcommands to create validator keys and '
+        'help create the genesis block',
+        parents=[parent_parser])
     admin_sub = parser.add_subparsers(title='subcommands', dest='subcommand')
     admin_sub.required = True
     add_genesis_parser(admin_sub, parent_parser)

cli/sawtooth_cli/admin_command/genesis.py

@@ -25,7 +25,20 @@
 def add_genesis_parser(subparsers, parent_parser):
     """Creates the arg parsers needed for the genesis command.
     """
-    parser = subparsers.add_parser('genesis', parents=[parent_parser])
+    parser = subparsers.add_parser(
+        'genesis',
+        help='Creates the genesis.batch file for initializing the validator',
+        description='Generates the genesis.batch file for '
+        'initializing the validator.',
+        epilog='This command generates a serialized GenesisData protobuf '
+        'message and stores it in the genesis.batch file. One or more input '
+        'files (optional) can contain serialized BatchList protobuf messages '
+        'to add to the GenesisData. The output shows the location of this '
+        'file. By default, the genesis.batch file is stored in '
+        '/var/lib/sawtooth. If $SAWTOOTH_HOME is set, the location is '
+        '$SAWTOOTH_HOME/data/genesis.batch. Use the --output option to change '
+        'the name of the file.',
+        parents=[parent_parser])
 
     parser.add_argument(
         '-o', '--output',

cli/sawtooth_cli/admin_command/keygen.py

@@ -29,7 +29,20 @@ def add_keygen_parser(subparsers, parent_parser):
         parent_parser (:obj:`ArguementParser`): The parent of the subcomman
             parsers.
     """
-    parser = subparsers.add_parser('keygen', parents=[parent_parser])
+    description = 'Generates keys for the validator to use when signing blocks'
+
+    epilog = (
+        'The private and public key pair is stored in '
+        '/etc/sawtooth/keys/<key-name>.priv and '
+        '/etc/sawtooth/keys/<key-name>.pub.'
+    )
+
+    parser = subparsers.add_parser(
+        'keygen',
+        help=description,
+        description=description + '.',
+        epilog=epilog,
+        parents=[parent_parser])
 
     parser.add_argument(
         'key_name',

cli/sawtooth_cli/batch.py

@@ -35,7 +35,11 @@ def add_batch_parser(subparsers, parent_parser):
             subparsers: Add parsers to this subparser object
             parent_parser: The parent argparse.ArgumentParser object
     """
-    parser = subparsers.add_parser('batch')
+    parser = subparsers.add_parser(
+        'batch',
+        help='Display information about batches and submit new batches',
+        description='Provides subcommands to display Batch information and '
+        'submit Batches to the validator via the REST API.')
 
     grand_parsers = parser.add_subparsers(title='grandchildcommands',
                                           dest='subcommand')
@@ -47,37 +51,35 @@ def add_batch_parser(subparsers, parent_parser):
 
 
 def add_batch_list_parser(subparsers, parent_parser):
-    epilog = '''details:
-        Lists committed batches from newest to oldest, including their id (i.e.
-    header signature), transaction count, and their signer's public key.
-    '''
+    description = (
+        'Displays all information about all committed Batches for '
+        'the specified validator, including the Batch id, public keys of all '
+        'signers, and number of transactions in each Batch.')
+
     subparsers.add_parser(
-        'list', epilog=epilog,
+        'list',
+        description=description,
         parents=[base_http_parser(), base_list_parser()],
         formatter_class=argparse.RawDescriptionHelpFormatter)
 
 
 def add_batch_show_parser(subparsers, parent_parser):
-    epilog = '''details:
-        Shows the data for a single batch, or for a particular property within
-    that batch or its header. Displays data in YAML (default), or JSON formats.
-    '''
     show_parser = subparsers.add_parser(
-        'show', epilog=epilog,
+        'show',
+        description='Displays information for the specified Batch.',
         parents=[base_http_parser(), base_show_parser()],
         formatter_class=argparse.RawDescriptionHelpFormatter)
+
     show_parser.add_argument(
         'batch_id',
         type=str,
         help='the id (i.e. header_signature) of the batch')
 
 
 def add_batch_status_parser(subparsers, parent_parser):
-    epilog = '''details:
-        Fetches the statuses for a set of batches.
-    '''
     status_parser = subparsers.add_parser(
-        'status', epilog=epilog,
+        'status',
+        description='Displays the status of the specified Batch id or ids.',
         parents=[base_http_parser()])
 
     status_parser.add_argument(
@@ -103,6 +105,10 @@ def add_batch_status_parser(subparsers, parent_parser):
 def add_batch_submit_parser(subparsers, parent_parser):
     submit_parser = subparsers.add_parser(
         'submit',
+        description='Sends Batches to the REST API to be submitted to the '
+        'validator. The input must be a binary file containing a '
+        'binary-encoded BatchList of one or more batches with any number '
+        'of transactions.',
         parents=[base_http_parser(), parent_parser])
 
     submit_parser.add_argument(

cli/sawtooth_cli/block.py

@@ -29,28 +29,38 @@ def add_block_parser(subparsers, parent_parser):
             subparsers: Add parsers to this subparser object
             parent_parser: The parent argparse.ArgumentParser object
     """
-    parser = subparsers.add_parser('block')
+    parser = subparsers.add_parser(
+        'block',
+        description='Provides subcommands to display information about the '
+        'blocks in the current blockchain.',
+        help='Display information on blocks in the current blockchain')
+
+    grand_parsers = parser.add_subparsers(
+        title='grandchildcommands',
+        dest='subcommand')
 
-    grand_parsers = parser.add_subparsers(title='grandchildcommands',
-                                          dest='subcommand')
     grand_parsers.required = True
 
-    epilog = '''details:
-        Lists committed blocks from the newest to the oldest, including
-    their id (i.e. header signature), batch and transaction count, and
-    their signer's public key.
-    '''
+    description = (
+        'Displays information for all blocks on the current '
+        'blockchain, including the block id and number, public keys all '
+        'of allsigners, and number of transactions and batches.')
+
     grand_parsers.add_parser(
-        'list', epilog=epilog,
+        'list',
+        help='Displays information for all blocks on the current blockchain',
+        description=description,
         parents=[base_http_parser(), base_list_parser()],
         formatter_class=argparse.RawDescriptionHelpFormatter)
 
-    epilog = '''details:
-        Shows the data for a single block, or for a particular property within
-    that block or its header. Displays data in YAML (default), or JSON formats.
-    '''
+    description = (
+        'Displays information about the specified block on '
+        'the current blockchain')
+
     show_parser = grand_parsers.add_parser(
-        'show', epilog=epilog,
+        'show',
+        help=description,
+        description=description + '.',
         parents=[base_http_parser(), base_show_parser()],
         formatter_class=argparse.RawDescriptionHelpFormatter)
     show_parser.add_argument(

cli/sawtooth_cli/config.py

@@ -53,7 +53,8 @@ def add_config_parser(subparsers, parent_parser):
     """
     parser = subparsers.add_parser(
         'config',
-        help='commands to modify on-chain settings',
+        help='Change genesis block settings and create, view, and '
+        'vote on settings proposals',
         description='Sawtooth supports storing settings on-chain. The '
                     'subcommands provided here can be used to view the '
                     'current proposals, create proposals and vote on existing '
@@ -70,7 +71,7 @@ def add_config_parser(subparsers, parent_parser):
     # transactions for on-chain settings
     genesis_parser = config_parsers.add_parser(
         'genesis',
-        help='creates a genesis batch file of settings transactions',
+        help='Create a genesis batch file of settings transactions',
         description='Creates a Batch of settings proposals that can be '
                     'consumed by "sawtooth admin genesis" and used '
                     'during genesis block construction.'
@@ -106,7 +107,7 @@ def add_config_parser(subparsers, parent_parser):
 
     proposal_parser = config_parsers.add_parser(
         'proposal',
-        help='view, create or vote on settings change proposals',
+        help='View, create or vote on settings change proposals',
         description='sawtooth-settings supports a simple voting mechanism for '
                     'applying changes to on-change settings.  These commands '
                     'provide tools to view, create or vote on proposed '
@@ -213,7 +214,7 @@ def add_config_parser(subparsers, parent_parser):
 
     settings_parser = config_parsers.add_parser(
         'settings',
-        help='list and show on-chain settings',
+        help='List and show on-chain settings',
         description='Displays the values of currently active on-chain '
                     'settings.')
     settings_parsers = settings_parser.add_subparsers(