gistfile1.rst

The setup:

• Some top level tasks
• A 'docs' submodule
• docs.build is configured to be the default task for 'docs'
• So, 'invoke docs' == 'invoke docs.build'. Either is allowed.

The question is, how should this setup display in --list? Our options:

1. Fab 1.x style: display both, no indication of what maps to what:

   $ invoke --list
       top
       level
       docs
       docs.clean
       docs.build
       docs.browse

2. Super-compact style: display only the default/shorthand. Kind of meh, "hides" the "real" task name:

   $ invoke --list
       top
       level
       docs
       docs.clean
       docs.browse

3. Compact style: focus on the default/shorthand, but display the "real" name alongside:

   $ invoke --list
       top
       level
       docs (docs.build)
       docs.clean
       docs.browse

4. Doubled-up/highly explicit style: still show what the default maps to, but ALSO show the "real" name in-place:

   $ invoke --list
       top
       level
       docs (docs.build)
       docs.clean
       docs.build
       docs.browse

5. Variation on either of the above two, the "alongside" display could be compacted a bit, e.g.:

   $ invoke --list
       top
       level
       docs (.build)
       docs.clean
       docs.build
       docs.browse

   or:

   docs(.build)

   or:

   docs[.build]

   or so forth.

Second thought, if we're focusing on the target of an alias w/ its aliases in parentheses, that actually implies it's more consistent to put default tasks' collection names in parens too. I.e. backwards from the above:

$ invoke --list
    deploy (release)
    docs.build (docs)
    docs.clean
    docs.browse

Will go with this for now. Again, subject to change & likely to have different list format options available either way (e.g. ye olde nested view).

👍 on the last one actually quite clear.