Makes the OpenAPI docs generation more robust (#14175)

.pre-commit-config.yaml

@@ -37,9 +37,11 @@ repos:
         name: Generating OpenAPI docs for Mintlify
         language: system
         entry: ./scripts/generate_mintlify_openapi_docs.py
+        pass_filenames: false
         files: |
             (?x)^(
                 .pre-commit-config.yaml|
-                src/prefect/server/.*|
+                src/prefect/server/api/.*|
+                src/prefect/server/schemas/.*|
                 scripts/generate_mintlify_openapi_docs.py
             )$

scripts/generate_mintlify_openapi_docs.py

@@ -15,6 +15,8 @@
 SinglePage = str
 PageGroup = dict[str, Any]
 
+MINTLIFY_SCRAPE = ["npx", "--yes", "@mintlify/scraping@3.0.123"]
+
 
 def docs_path() -> Path:
     return Path(__file__).parent.parent / "docs"
@@ -30,7 +32,7 @@ def current_version() -> str:
 
 
 def main():
-    ensure_mintlify_installed()
+    ensure_npx_environment()
 
     version = current_version()
     server_docs_path = docs_path() / f"{version}/api-ref/server/"
@@ -50,23 +52,16 @@ def main():
     write_mint(mint_json)
 
 
-def ensure_mintlify_installed():
-    result = subprocess.run(["which", "mintlify-scrape"], capture_output=True)
-    if result.returncode == 0:
-        return
-
-    result = subprocess.run(["which", "npm"], capture_output=True)
+def ensure_npx_environment():
+    result = subprocess.run(["which", "npx"], capture_output=True)
     if result.returncode != 0:
         print(
-            "Neither `@mintlify/scraping` nor `npm` are installed.  Please make sure "
-            "you have a working `npm` installation before generating API docs.",
+            "`npx` is not installed.  Please make sure you have a working `npm` "
+            "installation before generating API docs.",
             file=sys.stderr,
         )
         sys.exit(1)
 
-    print("@mintlify/scraping is not installed. Installing...")
-    subprocess.check_call(["npm", "install", "-g", "@mintlify/scraping"])
-
 
 def generate_schema_documentation(version: str, server_docs_path: Path) -> Navigation:
     """Write the current OpenAPI schema to the given path, generates documentation files
@@ -80,8 +75,8 @@ def generate_schema_documentation(version: str, server_docs_path: Path) -> Navig
         f.flush()
 
     result = subprocess.run(
-        [
-            "mintlify-scrape",
+        MINTLIFY_SCRAPE
+        + [
             "openapi-file",
             schema_path,
             "-o",
@@ -96,7 +91,12 @@ def generate_schema_documentation(version: str, server_docs_path: Path) -> Navig
     # mintlify-scrape will output a list of suggestions for navigation objects, prefixed
     # with a header "navigation object suggestion:"
     output = result.stdout.replace("navigation object suggestion:\n", "")
-    suggestions = json.loads(output)
+    try:
+        suggestions = json.loads(output)
+    except Exception:
+        print("Couldn't understand the output of mintlify-scrape:", file=sys.stderr)
+        print(output, file=sys.stderr)
+        raise
     return suggestions