Mention 'tahoe run' in running.html, and improve tahoe --help text

[davidsarah]

From #355:

I guess you missed the existence of tahoe run because it isn't mentioned in source:docs/running.html. Perhaps we should change that document to describe tahoe run instead of tahoe start? (That document is intended for the beginner, who might prefer the simplicity of tahoe run.)

Something else that might help is if the output of tahoe --help separated node control (start, stop, restart, run, create-client, create-introducer) from filesystem usage (put, get, rm, etc.)

These seem like good doc improvements to me. They're independent of the other problems with tahoe run in #355.

[warner]

FYI, I don't think there's a way to override the alphabetical sorting of subcommands in twisted.python.usage.Option's base-class code which generates the output that "bin/tahoe" (without a subcommand) provokes. But if you override the "getUsage" method on allmydata.scripts.runner.Options (using allmydata.scripts.cli.GetOptions.getUsage as a template), you can probably replace the command listing with different text. This might be a good place to emit something else, like:

Commands for node admin:
   create-client       Create a client node.
   create-introducer   ...
   create-key-generator
   create-stats-gatherer
   start
   stop
   restart
   run
Commands for filesystem manipulation:
   mkdir
   ls
   cp
   ...

[warner]

Oh, one correction, usage.Option doesn't just sort its subcommands alphabetically: it retains the order in which they were provided (notice that bin/tahoe's output puts all the create-node commands at the start, and all the start/stop commands at the end.. this matches the way that _general_commands and subCommands are built in src/allmydata/scripts/runner.py).

That probably doesn't help insert extra text into the usage output, though.. you'll probably still have to override getUsage. But consider upcalling and then inserting text into the result (instead of writing something entirely new), because doing it that way will be more robust against the addition of new subcommands in the future.

[davidsarah]

Diff for source:docs/running.html to describe tahoe run

[davidsarah]

New help text:

$ tahoe
Usage:  tahoe <command> [command options]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers and exit.
      --version-and-path  Display version numbers and paths to their locations
                          and exit.
      --help              Display this help and exit.
Commands:

Node adminstration
    create-client              Create a client node.
    create-introducer          Create a introducer node.
    create-key-generator       Create a key generator service.
    create-stats-gatherer      Create a stats-gatherer service.

Using the filesystem
    mkdir                      Create a new directory
    add-alias                  Add a new alias cap
    create-alias               Create a new alias cap
    list-aliases               List all alias caps
    ls                         List a directory
    get                        Retrieve a file from the virtual drive.
    put                        Upload a file into the virtual drive.
    cp                         Copy one or more files.
    rm                         Unlink a file or directory in the virtual drive.
    mv                         Move a file within the virtual drive.
    ln                         Make an additional link to an existing file.
    backup                     Make target dir look like local dir.
    webopen                    Open a webbrowser to the root_dir
    manifest                   List all files/dirs in a subtree
    stats                      Print statistics about all files/dirs in a
                               subtree
    check                      Check a single file or directory
    deep-check                 Check all files/directories reachable from a
                               starting point

Debugging
    debug                      debug subcommands: use 'tahoe debug' for a list

Controlling a node
    start                      Start a node (of any type).
    stop                       Stop a node.
    restart                    Restart a node.
    run                        Run a node synchronously.

c:\Python26\Scripts\tahoe-script.py:  must specify a command

[davidsarah]

Rearranging the command groups and adding some text about tahoe <command> --help at the bottom:

$ tahoe --help
Usage:  tahoe <command> [command options]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers and exit.
      --version-and-path  Display version numbers and paths to their locations
                          and exit.
      --help              Display this help and exit.
Commands:

Administration
    create-client              Create a client node.
    create-introducer          Create a introducer node.
    create-key-generator       Create a key generator service.
    create-stats-gatherer      Create a stats-gatherer service.

Controlling a node
    start                      Start a node (of any type).
    stop                       Stop a node.
    restart                    Restart a node.
    run                        Run a node synchronously.

Debugging
    debug                      debug subcommands: use 'tahoe debug' for a list

Using the filesystem
    mkdir                      Create a new directory
    add-alias                  Add a new alias cap
    create-alias               Create a new alias cap
    list-aliases               List all alias caps
    ls                         List a directory
    get                        Retrieve a file from the virtual drive.
    put                        Upload a file into the virtual drive.
    cp                         Copy one or more files.
    rm                         Unlink a file or directory in the virtual drive.
    mv                         Move a file within the virtual drive.
    ln                         Make an additional link to an existing file.
    backup                     Make target dir look like local dir.
    webopen                    Open a webbrowser to the root_dir
    manifest                   List all files/dirs in a subtree
    stats                      Print statistics about all files/dirs in a
                               subtree
    check                      Check a single file or directory
    deep-check                 Check all files/directories reachable from a
                               starting point

Please run 'tahoe <command> --help' for more details on each command.

[warner]

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that self.subCommands gets set back to its original value even if an exception is raised in the middle, but that code is only going to get invoked after subCommands is used and just before the whole process exits, so it probably isn't too important.

Please double-check that the trick you're using will work against our oldest supported version of Twisted (which is.. aagh! zooko! well, it used to be in README, and then in INSTALL, and now I can't find it in the docs/ directory. So first harass Zooko to ressurect our human-readable dependency list, then check it for the oldest version of Twisted that we claim compatibility with, and then check that version of Twisted :). I believe usage.Options has remained unchanged for years, so I expect your trick to work everywhere, but it'd be good to make sure.

[zooko]

Our "human-readable" dependency list is in _auto_deps.py, and it says "Twisted >= 2.4.0". If David-Sarah's hack doesn't work with Twisted 2.4.0 we should consider raising the minimum version requirement. Currently on our Supported builders the oldest version of Twisted in use is Twisted 8.1.0 (in Debian 5.0 Lenny and in NetBSD 4). If David-Sarah's hack works for all versions of Twisted > X for some X <= 8.1.0 then I would support it.

[warner]

ok, I think we need a pointer to it from some other human-readable document, like the way that most projects have a README or an INSTALL which tells you what the dependencies are (grep auto_deps README docs/* shows nothing). I know that you've tried hard to not frighten people with such details, but I think they need to be findable by the people who want them.

But anyways, I don't see any changes to twisted.python.usage between 2.4.0 and current trunk (which is 9.0.0+), so I think David-Sarah's hack should work equally well across that range.

[davidsarah]

Looking at the source for Twisted's usage.py, this hack should work going back to ​revision 7653 in July 2003, which introduced the getUsage method. We depend on getUsage elsewhere, e.g. in cli.py. That would have been way before Twisted 2.4.0, which was released in 2006.

I agree about the try: finally:.

[davidsarah]

Diff for source:src/allmydata/scripts/runner.py​ to split usage into groups (better approach)

[davidsarah]

Replying to warner:

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that self.subCommands gets set back to its original value even if an exception is raised in the middle, [...]

I changed it to use another class so that self.subCommands doesn't need to be modified in the Options instance.

[davidsarah]

Split tahoe --help options into groups

[davidsarah]

Change running.html to describe 'tahoe run'

[davidsarah]

The command grouping is a very simple patch, and I think it does help make the tahoe --help text more readable. Anyone want to review it for 1.6?

[zooko]

Thank you! I really like the command grouping! Applied as b94b9af1896ec527, b079f32da2aa0746, a1444d9367554df7, and 5c04fd689ab4b3bf.