Use as an API; Specify help text in primary entrypoint.

[Descent098]

Feature request

I'm wondering if it would be possible to make the main entrypoint (the docopt_completion() function), usable as an API. Currently it assumes you are running it from the command and wrapping an existing command, but it would be nice to be able to generate the auto-completion files with manually specified docopt strings.

Example use cases

I am currently working on a project (for full context here is the github link) that allows you to register ad-hoc sub-commands that are parsed at runtime. This means that when someone 'registers' one of the aliases I would like to be able to create an autocompletion file from the running script. The problem is since the docopt_completion() function is expecting the command to implicitly collect the helptext I can't dynamically generate the files.

Ideally it would be possible to add an additional flag to just pass our own help text instead of needing to run the script over the command. For example something like

from infi.docopt_completion import docopt_completion

usage = get_usage() # This would do the dynamic docopt generation

docopt_completion(None, usage = usage)

This also would be useful for be nice for giving you more direct customization of the resulting completion files, and give you the option to generate the files ahead of time before you've finished implementing a feature. For example if there are common defaults you could just specify the docopt string to include these permutations for autocomplete, but not clutter up the main usage info.

I apologize for how lengthy this issue is, just wanted to make sure all the rationale was included.