Explicitly document how best to exit/abort a task w/o a traceback

[pfmoore]

I'm not sure what is the best way to report failure in a task. I can raise an exception, but if I do that the main program produces a fairly unfriendly traceback for the user. I can simply print a message and exit the task, but if I do that presumably other tasks specified on the command line, or as post-tasks, will run, and I'd expect a "proper" task failure to abort the whole run.

I've checked the documentation, but there's not actually a huge amount I can see on how to write a task definition. Most of it's simply standard Python, so I guess that's fine, but if I've missed something I apologise.

[bitprophet]

See the commentary in #476 - tl;dr sys.exit("Oops") or raise invoke.Exit("oops") ought to result in traceback-less exits. Former is more direct, latter is easier for users to catch if catchability is desired.

I guess the sys.exit approach falls under "standard Python", but given this has come up at least 3 times over the last few years, I'm thinking we should probably put in something explicit in the docs somewhere. Suggestions as to what would've been the most obvious spot, are welcome!

I'll leave this open as a "update the docs" placeholder until then. Thanks!

[pfmoore]

Thanks for the clarification - on reflection, sys.exit is pretty obvious, but it never occurred to me 😦

When I was searching, I was looking for a "writing tasks" section in the documentation. Maybe the best approach would be to include such a section - it would obviously be fairly simple ("Tasks are written using standard Python and can do anything you would normally do in a Python script. To exit a task cleanly without running subsequent tasks, just use sys.exit()") but could note the existence of some of the commonly used helpers like run().

Actually, one other thing I struggled to find, was how tasks get their arguments (it would also fit in a "Writing tasks" section). The simple situations are pretty easy to work out from the examples, but more complex cases are a struggle. For example, I have a need for a series of tasks, all of which should take a --target option, and when run in the same command, they should all use the same target. So

invoke --target foo create_setup add_tests add_docs

should run the three tasks all with a target of foo. Using a target argument on each task means the user has to specify it 3 times. Using configuration (as documented here) doesn't allow the user to specify the target on the command line. I'm sure there's a way, possibly involving adding a custom core argument) but I couldn't find it...