feat: troubleshooting docs (#175)

Author: joshuarli

README.md

@@ -318,8 +318,9 @@ def main(context: dict[str, str]) -> int:
 
 ### colima
 
-Since devenv 1.14.0, colima (and the docker CLI needed to interact with it) should have been installed globally for you during bootstrap.
-If you're on an older version, run `devenv update` twice to get global colima.
+Since devenv 1.14.0, colima (and the docker CLI needed to interact with it)
+should have been installed globally for you during bootstrap.
+If you're on an older version, run `devenv update`.
 
 
 ### gcloud

devenv/constants.py

@@ -6,6 +6,21 @@
 import pwd
 import typing
 
+troubleshooting_help = """\
+===============
+Troubleshooting
+===============
+
+Problem? First try running `devenv doctor`.
+If that doesn't help, then proceed:
+
+Internal living doc (more up-to-date):
+https://www.notion.so/sentry/devenv-troubleshooting-1448b10e4b5d8080ba04f452e33de48d
+
+Public doc:
+https://develop.sentry.dev/development-infrastructure/environment/#troubleshooting
+"""
+
 version = importlib.metadata.version("sentry_devenv")
 
 CI = os.getenv("CI")

devenv/main.py

@@ -12,6 +12,7 @@
 from devenv import sync
 from devenv import update
 from devenv.constants import home
+from devenv.constants import troubleshooting_help
 from devenv.constants import user
 from devenv.constants import version
 from devenv.lib.config import read_config
@@ -51,7 +52,10 @@ def devenv(argv: Sequence[str], config_path: str) -> ExitCode:
 
     # TODO: Search for modules in work repo
 
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=troubleshooting_help,
+    )
     parser.add_argument("--version", action="version", version=version)
     subparser = parser.add_subparsers(
         title=argparse.SUPPRESS,
@@ -62,7 +66,12 @@ def devenv(argv: Sequence[str], config_path: str) -> ExitCode:
 
     for info in modinfo_list:
         # Argparse stuff
-        subparser.add_parser(info.command, help=info.help)
+        subparser.add_parser(
+            info.command,
+            help=info.help,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+            epilog=troubleshooting_help,
+        )
 
     if len(argv) == 1:
         parser.print_help()

devenv/sync.py

@@ -5,6 +5,7 @@
 import os
 from collections.abc import Sequence
 
+from devenv.constants import troubleshooting_help
 from devenv.lib.context import Context
 from devenv.lib.modules import DevModuleInfo
 from devenv.lib.modules import require_repo
@@ -35,7 +36,10 @@ def main(context: Context, argv: Sequence[str] | None = None) -> int:
     }
 
     with contextlib.chdir(repo.path):
-        return module.main(context_compat)  # type: ignore
+        rc = module.main(context_compat)
+        if rc != 0:
+            print(troubleshooting_help)
+        return rc  # type: ignore
 
 
 module_info = DevModuleInfo(