Document how session.run fails, and how to handle failures

[DiddiLeija]

Closes #517.

This PR added a docstring to explain how session.run fails and stop the session. Also, I documented how to handle these failures, like described in #517.

[DiddiLeija]

cc @cjolowicz @ktbarrett

[cjolowicz]

Can we simplify the example? In particular, I'd be wary of using git stashas an example because it (temporarily) modifies the user's work tree.

What do you think about using something like this as an example?

try:
    session.run("coverage", "run", "-m", "pytest")
finally:
    # Display coverage report even when tests fail.
    session.run("coverage", "report")

I've found this to be a useful real-world idiom, especially when you're in the habit of writing a failing test first.

[ktbarrett]

I agree on simplifying the example. As I've discovered it's a little more involved than just git stash pop and I don't want to screw up people's working tree who are trying the feature out.

[DiddiLeija]

Done.

[cjolowicz]

Thanks!