[robotpy] Improve debug information failures that require running scan-header, update-yaml, and update-build-info (#8388)

Fixes #8386 

Was already working on this when more people started hitting issues so I
prioritized getting this PR up. This updates the wrapper script to look
for the 3 biggest categories of "everything should be fine if you run
this step first" tool failures.

Co-authored-by: Gold856 <117957790+Gold856@users.noreply.github.com>
Co-authored-by: David Vo <auscompgeek@users.noreply.github.com>

shared/bazel/rules/robotpy/wrapper.py

@@ -16,6 +16,68 @@ the build.
 """
 
 
+README_LINK = "https://github.com/wpilibsuite/allwpilib/blob/2027/README-RobotPy.md"
+
+
+def print_failure_message(tool, args):
+
+    extra_error_message = None
+
+    # Some tools are more likely to fail, and can give a better error description to help the user debug their problem.
+    if tool == "semiwrap.tool":
+        if args[0] == "scan-headers":
+            extra_error_message = f"""
+#########################################################################################
+The scan header test has failed. This likely means that you have removed header
+files that are used by the project or have added new headers that aren't tracked
+(or explicitly ignored) by the project. The text printed up above this message
+should tell you want needs to be added / removed from this project's pyproject.toml file.
+
+Please see this readme for more information:
+{README_LINK}#1-scan-headers
+#########################################################################################
+"""
+
+    elif tool == "semiwrap.cmd.header2dat":
+        extra_error_message = f"""
+#########################################################################################
+The 'header to dat file' step has failed. The most probable cause for this is that you
+have yaml files that don't exist or are out of date called out in this project's
+pyproject.toml file, and need to be regenerated running a tool that looks like this:
+
+bazel run //<project>:write_<library_name>-update-yaml
+
+Please see this readme for more information:
+{README_LINK}#2-update-yaml
+#########################################################################################
+"""
+    elif tool.startswith("semiwrap.cmd.dat"):
+        extra_error_message = f"""
+#########################################################################################
+An auto generation error has occurred. The most probable cause for this that the bazel
+build scripts need to updated, running a tool that looks like this:
+
+bazel run //<project>:<library_name>-generator.generate_build_info
+
+Please see this readme for more information:
+{README_LINK}#3-generate-build-info
+#########################################################################################
+"""
+
+    print("-------------------------------------")
+    print("Failed to run wrapped tool.")
+    print(f"CWD: {os.getcwd()}")
+    print(f"Tool: {tool}, Args:")
+    for a in args:
+        print("  ", a)
+    print("-------------------------------------")
+
+    if extra_error_message:
+        print(extra_error_message)
+    else:
+        print(f"Please see the robotpy readme: {README_LINK}")
+
+
 def main():
     tool = sys.argv[1]
 
@@ -37,17 +99,11 @@ def main():
         tool_main()
     except SystemExit as e:
         if e.code != 0:
-            raise Exception(
-                "sys.exit() explicitly called with a non-zero error code", e
-            )
+            print_failure_message(tool, args)
+            print(f"sys.exit() explicitly called with a non-zero error code: {e.code}")
+            sys.exit(e.code)
     except:
-        print("-------------------------------------")
-        print("Failed to run wrapped tool.")
-        print(f"CWD: {os.getcwd()}")
-        print(f"Tool: {tool}, Args:")
-        for a in args:
-            print("  ", a)
-        print("-------------------------------------")
+        print_failure_message(tool, args)
         raise