Add documentation links and helpful descriptions to error messages

[0x2b3bfa0]

p1

The following have recently been documented in https://cml.dev/doc, but should also have better CLI errors pointing to said docs:

• cml send-comment --update: Raises 'commit_id has been locked' error #888
  • https://cml.dev/doc/ref/send-comment#GitHub
• send-comment PR for commit sha \"HEAD\" not found #880
  • uses: actions/checkout@v3, with.ref: ${{ github.event.pull_request.head.sha }}
  • https://cml.dev/doc/usage?tab=GitHub
• cml send-github-check hangs and does not report #941
  • use default GITHUB_TOKEN or GitHub App token, not Personal Access Token
  • https://cml.dev/doc/ref/send-github-check
• Error "Resource not accessible by integration" is not helpful #595
  • Resource not accessible by integration
  • Error: Forbidden
    • "Ensure permissions are granted as per https://cml.dev/doc/self-hosted-runners?tab=GitLab#personal-access-token"?
• Docker volumes in GH should not just throw an unsupported error #911 (?)
• Handle environments without Git with a helpful error message #628
• Unmask catch-all token exceptions #563
• Gitlab on premise misleading "API not found" due to SSL issues #472
• Improve BitBucket unauthorized error message #813
• Better error reporting/debugging for BitBucket #816
• Error: Failed preparing Gitlab runner: Forbidden in cml-cloud-case #835

p2

• #581/r656156462: links like https://err[or].cml.dev/YpQ on errors that are especially tricky to explain inline or require additional context [...] e.g. https://error.dvc.org/no-dvc-cache
• --help should print URL #1222 cml CMD --help links to https://cml.dev/doc/ref/CMD

See also

• #595/862336393: See Unmask catch-all token exceptions #563 and #563/r640709086 for a good compromise between error message integrity and end user helpfulness.

try {
  operation();
} catch (error) {
  if (error.message === 'Obscure error')
    error.message += ', please try toggling the "more magic" switch';
  throw error;
}

[0x2b3bfa0]

Linking to #628, #595, #563 and #472 for future references.

[casperdcl]

Also

super minor: maybe newline instead of ', '

[casperdcl]

Now that we have iterative/cml.dev#112, can we also add a https://cml.dev/doc/ref/subcommand link to all subcommand --help output like DVC does? #1222

Meanwhile error messages can link to subsections of the command reference for elucidation.