Review of the CLI and supporting documentation

[vladimir-v-diaz]

Description of issue or feature request:

The CLI tool and supporting documentation were recently completed for the CII silver badge. However, their usability could sure use a fresh set of eyes. The following docs and module need a review:

(1) QUICKSTART (doc)
(2) CLI (doc)
(3) CLI EXAMPLES (doc)
(4) repo.py (CLI module)

[vladimir-v-diaz]

@yashsriv @SantiagoTorres
Can we trade code reviews? I'd like to trade this review request for in-toto/in-toto#209, in-toto/in-toto#206, in-toto/in-toto#208, and the contributions for the CII proposals.

I'd mostly like feedback on the usability of the CLI and accuracy/readability of the docs. Once these have been verified, I intend to mock test repo.py and finish the docstrings.

[vladimir-v-diaz]

Sharing @SantiagoTorres's review of the CLI and supporting documents to better track the fixes/changes made in the referenced pull requests.

== quickstart.md ==

• would be nice to refer to the installation instructions (e.g., "we
  assume you installed tuf using any of the instructions [here])
• There is no mention as to when the directory "tufrepo" was made,
  that'd be helpful to mention either on the tool and/or the client
  side.
• The slugs could be improved a little bit. Probably add a couple of
  instances of what was created (e.g., using tree).
• I wonder if you'd like to try a very simple attack setup (e.g.,
  replace the file in tufrepo/targets/testfile)

== CLI.md ==

• I'm not entirely happy/confident with the default password choice.
  Maybe it'd be a good idea to generate a sensible random one and echo
  it to the terminal?
• the --sign switch should be presented earlier.
• There arer instances of "may be named anything". I'm not a native
  speaker, but this sounds odd to me...
• It appears that the "note: in the future, the user might have the
  option of disabling automatic signing" is a stray/old comment.
• Header: s/Delegation/Delegations/
• I would rephrase the text in clean

== CLI_examples.md ==

• xkey and xkey2 are never created. Although it may be obvious it's
  worth mentioning it
• Please inline what you're doing, even if it's repeating yourself.

= Repo.py =

• I don't think the from future import print_function is necessary
  anymore. I don't think we're supporting old (2.6-) versions of python
• you require colorama, but you don't explicitly have it in the
  requirements.
• Can't you get the supported key types from somewhere else?
• I don't understand the docstring on line 101, is process_arguments
  a descriptive-enough function name?
• can I actually do init + clean + add + remove in one invocation? I'd
  probably want some validation as to what can be done together.
• line 208 writes root, then everything is re-written again on line
  227. Could it be possible that the logic can be coalesced into one if
  statement to obtain the delegatee and have everything outside of the ifs?
• same goes for the if-statement on revoke (and probably everywhere else)
• the write to live repo operation seems to happen everywehere, could
  we factor it out of the specific handlers?
• 288, 292, 296 read like magic strings to me, could we probably use
  explicit constants?
  Also, can we turn the else: into a guard clause?
• 307: "the filenames are written to .pub and (private
  key)" -> The keypair is written to disk with the filenames
  for the private key, and .pub for the public key. All in all
  this comment can be simplified quite a lot
• 336: do we necessarilly have to use concatenation?
• 469: is that the only thing that can go wrong in functions downstream?
• on revoke you use =='s, but on sign_role you use membership in
  singly-membered lists (not even a set). Is this intentional?
• line 520 definitely requires a comment, or propperly importing the constant
• do consider ioctl file locking on line 585...
• 629 consider using a set to check for membership.
• review spacing, there are a lot of functions with 5 lines separating
  them and there are others with 3
• 914: the metavar is missing a >
• IMHO, setting the logging level is too verbose, can be made terser
  (e.g., put them on a list and then look up in the list using the
  parameter passed...).

[lukpueh]

Closing due to uncertain future of TUF cli. Re-visit with #811.