How can text in the options configuration of Docopt be wrapped?

Question

I have a few detailed option specifications in the docstring used for configuration of Docopt. Some of the items are quite lengthy. Is there a way of wrapping the text to make it more legible or to make it fit to a line width more easily?

Let's say the relevant bit of text in the docstring is the following:

Usage:
    program [options]

Options:
    -h, --help                      Show this help message.
    -c, --configuration=CONF        Configuration (file) [default: None]
    -f, --files=FILESLIST           Comma-delimited list of input data files [default: 169888_ttH_el.root]
    -v, --variables=VARIABLESLIST   Comma-delimited list of variables to plot [default: trk_pt]
    -t, --tree=TREE                 Tree in input data files [default: mini]
    -u, --username=USERNAME         Username
    -t, --topanalysis=DIRECTORY     Directory of TopRootCore or TopAnalysis [default: /home/user/Dropbox/TopAnalysis]
    -s, --superlongoption=TEST      This is a very long option that requires a bit of text to explain it. [default: 101001011011101010010100110101010]
    --version                       Show the version and exit.

Would it be possible wrap the text in a style something like the following?

Usage:
    program [options]

Options:
    -h, --help                      Show this help message.
    -c, --configuration=CONF        Configuration (file) [default: None]
    -f, --files=FILESLIST           Comma-delimited list of input data files
                                    [default: 169888_ttH_el.root]
    -v, --variables=VARIABLESLIST   Comma-delimited list of variables to plot
                                    [default: trk_pt]
    -t, --tree=TREE                 Tree in input data files [default: mini]
    -u, --username=USERNAME         Username
    -t, --topanalysis=DIRECTORY     Directory of TopRootCore or TopAnalysis
                                    [default: /home/user/Dropbox/TopAnalysis]
    -s, --superlongoption=TEST      This is a very long option that requires a
                                    bit of text to explain it.
                                    [default: 101001011011101010010100110101010]
    --version                       Show the version and exit.

Answer 1

How is option definition and description defined

The "secrets" are:

• option definition starts on any line, starting with - or -- (blanks ignored).
• option definition and option description must be delimited by at least two spaces.
• option description ends as soon as next option definition is found. Under-indented lines or blank lines do not end the description.
• any [defaults: block] being part of option description is valid and is used.

How to deal with description formatting

There are few things, which help using longer option descriptions or option definitions.

• Option description may start on any line following option definition.
• Option description may be wrapped.
  • Even under-indented lines are part of the option description.
  • To keep the text legible, keep option description indented to fixed column (e.g. 27 or 29 or other column you find practical). This is recommendation, not a rule)
  • [default: block] works well as long as it is considered part of option description. Even under-indented text works and blank lines are allowed too. Just put it anywhere before you define next option.
• The text Option: has no real meaning (regardless often use in tutorials of docopt). Options are recognized as any line starting with - or -- (initial blanks are ignored). This allows breaking the options into groups.
• be aware, that option definition and option description must be delimited by at least two spaces.

How was original code reorganized

Here is example of reorganized doc string from your example.

What was done:

• option description text starts at column 27
• where option definition ended in column 25 or later (not allowing 2 spaces before option description text starts), option description text was moved to next line.
• Options organized into logical groups (to show it is possible)
• Option groups got some description.

Rewritten example

Final code looks as follows:

"""
Usage:
    program [options]

General options:
  These things are rather general, so placed in this group of option.

    -h, --help            Show this help message.
    --version             Show the version and exit.
    -c, --configuration=CONF
                          Configuration (file) [default: None]

Directory and path related stuff:
  Whatever relates to file or directory, comes here.

    -f, --files=FILESLIST
                          Comma-delimited list of input data files
                          [default: 169888_ttH_el.root]
    -t, --tree=TREE       Tree in input data files [default: mini]
    -t, --topanalysis=DIRECTORY
                          Directory of TopRootCore or TopAnalysis
                          [default: /home/user/Dropbox/TopAnalysis]
Other things:
  Remaining options live here.

    -v, --variables=VARIABLESLIST
                          Comma-delimited list of variables to plot
                          [default: trk_pt]
    -u, --username=USERNAME
                          Username
    -s, --superlongoption=TEST
                          This is a very long option that requires a bit of text
                          to explain it.
                          [default: 101001011011101010010100110101010]
"""
if __name__ == "__main__":
    from docopt import docopt
    args = docopt(__doc__)
    print args