Add easy way to implement built-in help for each function about docopt HOT 10 CLOSED

Yes, we need some way to handle several help messages, and probably make it automatic to show them when entering prog help <topic>. Need to decide on API.

from docopt.

Here's my suggestion, based on checking the output of <cmd> help for a few different multi-command shell programs I've seen:

Usage: 
    myprog cmd1
    myprog cmd2
    myprog cmd3

Commands:
    cmd1    Swizzle the foorbar.
    cmd2    Spam the eggs.
    cmd3    Shave the yak.

That can give basic command help similar to the way Options: works currently.

For longer-form help (myprog help cmd1 / myprog cmd1 --help) I'd suggest an API like this:

arguments = docopt(__doc__, help={"cmd1": "some long string", "cmd2": "some long string", ...})

That is, have help be a dict of {subcommand: help string} In practice, the help strings might come from function docstrings, but whatever.

from docopt.

@jacobian your solution is very explicit, but I think there might be a way to collect help for commands in a more, maybe, distributed way.

I want to establish some use-case for different APIs to be discussed, let's base it on the following example (subset of git's CLI):

git.py
git_tag.py
git_branch.py

# git.py
""""
usage: git [--version] [--exec-path[=<path>]] [--html-path]
           [-p|--paginate|--no-pager] [--no-replace-objects]
           [--bare] [--git-dir=<path>] [--work-tree=<path>]
           [-c name=value] [--help]
           <command> [<args>]

The most commonly used git commands are:
   branch     List, create, or delete branches
   tag        Create, list, delete or verify a tag object signed with GPG

"""

# git_tag.py
"""
usage: git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
               <tagname> [<commit> | <object>]
       git tag -d <tagname>...
       git tag [-n[<num>]] -l [--contains <commit>] [<pattern>]
       git tag -v <tagname>...

"""

# git_branch.py
"""
usage: git branch [options] [-r | -a] [--merged | --no-merged]
       git branch [options] [-l] [-f] <branchname> [<start-point>]
       git branch [options] [-r] (-d | -D) <branchname>
       git branch [options] (-m | -M) [<oldbranch>] <newbranch>

"""

How would you organize code for such program, and how would you get usages together, etc?

from docopt.

Maybe something like that?

# git.py
""""
usage: git [--version] [--exec-path[=<path>]] [--html-path]
           [-p|--paginate|--no-pager] [--no-replace-objects]
           [--bare] [--git-dir=<path>] [--work-tree=<path>]
           [-c name=value] [--help]
           <command> [<args>]

The most commonly used git commands are:
   branch     List, create, or delete branches
   tag        Create, list, delete or verify a tag object signed with GPG

"""
from docopt import docopt
import git_tag, git_branch

args = docopt(doc=[__doc__, git_tag.__doc__, git_branch.__doc__])

This case probably can handle automatic printing of help, but how to decide when each of them should be printed? It can be done with a rule like if one set of usage-patterns always starts with same command, this set of usage pattern should be printed in case of (error and 1st argument is that command) or in case (help <that-command>).

Maybe instead of that rule, the command should be specified explicitly (like in @jacobian example), like:

args = docopt(__doc__, commands={'tag': git_tag.__doc__, 'branch': git_branch.__doc__})

Or maybe it's all redundant and we should just pass modules to docopt:

args = docopt(__doc__, subparsers=[git_tag, git_branch]) # expect modules to have `.__doc__`

Then, how should be the dispatch done then? Looks like #4, #17 and this one could not be solved separately.

from docopt.

I think I'd prefer the modules option. I think it is reasonable to to have to write a main help message, and then separate help messages for each command the program implements.

from docopt.

I think it's probably a good idea not to require that different commands live in different modules -- much of the time, I'm going to want to start with a single file, and having to break stuff up just so docopt can deal with sub-commands seems silly. It seems that explicitly passing in the objects/docstrings to parse is much more flexible.

I like

args = docopt(__doc__, subparsers=[git_tag, git_branch]) # expect modules to have `.__doc__`

Since it's pretty simple and obvious. However, I'd argue that git_tag and git_branch should probably be any callable with a __doc__, not forced to be modules.

That said, it's really not all that big a deal, and I'd happily take any API as long as it works!

from docopt.

@ansible07 @jacobian yes, passing modules/functions/etc with __doc__ member seems almost perfect to me. However I know that some people want to store docopt DSL source in a file (that's reasonable, huh?) especially if help messages are huge. This flexibility should be allowed.

Now I appeal mostly for this solution:

args = docopt(doc=[__doc__, git_tag.__doc__, git_branch.__doc__])

Which could be also done as:

args = docopt(doc=[open('git.docopt').read(),
                   open('git_tag.docopt').read(),
                   open('git_branch.docopt').read())

I will try implementing this in a branch, however, there is a potential problem that it could be not possible to figure out which help message to show in different situations (user error, prog help <command>, prog --help). If so—some other API is needed (probably passing dictionary instead of list).

from docopt.

+1 on a passing a dictionary to docopt(). Should the default help be the key "default"?

from docopt.

I no longer think that the proposed above APIs are good because of this flaw:

• Real, big, programs (like git) consist (behind the scene) of many sub-programs, which are often written in different languages.

The above APIs are python-only. Fortunately there are a bunch of docopt implementations in different languages—the ideal API would allow a central executable to make dispatch to different other executables. Maybe even to executables that don't make use of docopt.

from docopt.

I move this conversation to #4 "Subcommands and subparsers" since built-in help for each command is closely connected, and most usefully discussed together with that issue.

from docopt.