refactor/docs: improve compile_pip_requirements error message and docs

[brandonchinn178]

Resolution failure is the most common error from pip-compile, so we should make sure the error message is as clean as it can be. Previously, the output was cluttered with the exception traceback, which makes the actual error hard to see (several nested traceback).

The new output shortens it with a nicer message:

Checking _main/requirements_lock.txt
  ERROR: Cannot install requests<2.24 and requests~=2.25.1 because these package versions have conflicting dependencies.
ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

Fixes #2763

[rickeylev]

Thanks for taking the time to improve the error messaging!

Just a quick partial review.

[dougthor42]

LGTM, no blockers on my end. I'll let @rickeylev decide when to add to the merge queue.

Thanks!

[dougthor42]

Super nit: the sys.exit will mean you don't reach L239 so you don't actually need the else

except ...:
  if ...:
      sys.exit(1)
  raise

[brandonchinn178]

Sure; I like being explicit 🙂

[rickeylev]

LGTM

FYI: Avoid force-pushing during PR review. What happens is comments get "lost" -- one can see them on the "conversation" pane, but can't actually access them in the "review" pane. It also clobbers the history of changes, which makes it harder to see what was changed in between review.

[brandonchinn178]

@rickeylev Not sure what the build failure is, pretty sure it's ephemeral?

[rickeylev]

Yeah, looks like a temporary network error. I updated this head, so CI is running again and it's back in the merge queue.