Update Training API documentation

scripts/reference-generation/training/update_training_api_landing.py

@@ -5,11 +5,10 @@
 This script fetches the OpenAPI spec (either from local file or remote URL) and
 updates the Available Endpoints section in the training/api-reference.mdx landing page.
 """
-
+import requests
 import json
 import re
 from pathlib import Path
-import requests
 from typing import Dict, List, Tuple
 
 
@@ -23,6 +22,7 @@ def fetch_openapi_spec() -> dict:
             return json.load(f)
 
     # Fallback to remote
+    import requests  # Only import if needed for remote fetch
     print("  Fetching remote OpenAPI spec from https://api.training.wandb.ai/openapi.json")
     response = requests.get("https://api.training.wandb.ai/openapi.json")
     response.raise_for_status()
@@ -55,31 +55,24 @@ def parse_endpoints(spec: dict) -> Dict[str, List[Tuple[str, str, str, str]]]:
     return endpoints_by_tag
 
 
-def generate_endpoint_url(operation_id: str, tag: str, path: str) -> str:
-    """Generate the Mintlify URL for an endpoint based on its operation ID and tag."""
-    # Map tags to URL segments
-    tag_mapping = {
-        "Chat": "chat",
-        "Completions": "completions",
-        "Models": "models",
-        "Jobs": "jobs",
-        "Training": "training",
-        "Inference": "inference",
-        "Health": "health",
-        "Service": "service",
-    }
-
-    tag_segment = tag_mapping.get(tag, tag.lower().replace(" ", "-"))
-
-    # Convert operation_id to URL slug
-    # Remove the suffix like _get, _post, etc.
-    url_slug = re.sub(r'_(get|post|put|delete|patch)$', '', operation_id)
-    # Replace underscores with hyphens
-    url_slug = url_slug.replace('_', '-')
-
-    # If no operation_id, use the path to generate a slug
-    if not url_slug:
-        # Convert path like /v1/chat/completions to chat-completions
+def generate_endpoint_url(summary: str, tag: str, path: str) -> str:
+    """Generate the Mintlify URL for an endpoint based on its summary and tag.
+
+    Mintlify generates URL slugs from the operation summary (title), not operationId.
+    """
+    # Convert tag to URL segment (Mintlify lowercases and hyphenates)
+    tag_segment = tag.lower().replace(" ", "-")
+
+    # Convert summary to URL slug (Mintlify lowercases and hyphenates the title)
+    # Example: "Create Chat Completion" -> "create-chat-completion"
+    if summary:
+        url_slug = summary.lower().replace(" ", "-")
+        # Remove any non-alphanumeric characters except hyphens
+        url_slug = re.sub(r'[^a-z0-9-]', '', url_slug)
+        # Collapse multiple hyphens
+        url_slug = re.sub(r'-+', '-', url_slug)
+    else:
+        # Fallback: use path to generate a slug
         url_slug = path.strip('/').replace('/v1/', '').replace('/', '-')
 
     return f"https://docs.wandb.ai/training/api-reference/{tag_segment}/{url_slug}"
@@ -104,7 +97,7 @@ def generate_endpoints_section(endpoints: Dict[str, List[Tuple[str, str, str, st
         lines.append(f"\n### {category}\n\n")
 
         for method, path, operation_id, summary in endpoints[category]:
-            url = generate_endpoint_url(operation_id, category, path)
+            url = generate_endpoint_url(summary, category, path)
             lines.append(f"- **[{method} {path}]({url})** - {summary}\n")
 
     return "".join(lines)
@@ -124,8 +117,10 @@ def update_landing_page(endpoints_section: str):
     # Check if there's already an Available Endpoints section
     if "## Available Endpoints" in content:
         # Replace existing section
-        pattern = r'## Available Endpoints\n.*?(?=\n##|\Z)'
-        new_content = re.sub(pattern, endpoints_section.rstrip(), content, flags=re.DOTALL)
+        # Use (?=\n## [^#]) to only stop at level-2 headers (## ), not level-3 (###)
+        pattern = r'## Available Endpoints\n.*?(?=\n## [^#]|\Z)'
+        # Ensure proper trailing newline before the next section
+        new_content = re.sub(pattern, endpoints_section.rstrip() + "\n", content, flags=re.DOTALL)
     else:
         # Add the section before "## Related Resources" if it exists
         if "## Related Resources" in content:

training/api-reference.mdx

@@ -28,48 +28,26 @@ https://api.training.wandb.ai/v1
 
 ### chat-completions
 
-- **[POST /v1/chat/completions](https://docs.wandb.ai/training/api-reference/chat-completions/create-chat-completion-v1-chat-completions)** - Create Chat Completion
-- **[POST /v1/chat/completions/](https://docs.wandb.ai/training/api-reference/chat-completions/create-chat-completion-v1-chat-completions-)** - Create Chat Completion
+- **[POST /v1/chat/completions](https://docs.wandb.ai/training/api-reference/chat-completions/create-chat-completion)** - Create Chat Completion
 
 ### models
 
-- **[POST /v1/preview/models](https://docs.wandb.ai/training/api-reference/models/create-model-v1-preview-models)** - Create Model
-- **[DELETE /v1/preview/models/{model_id}/checkpoints](https://docs.wandb.ai/training/api-reference/models/delete-model-checkpoints-v1-preview-models--model-id--checkpoints)** - Delete Model Checkpoints
-- **[GET /v1/preview/models/{model_id}/checkpoints](https://docs.wandb.ai/training/api-reference/models/list-model-checkpoints-v1-preview-models--model-id--checkpoints)** - List Model Checkpoints
-- **[POST /v1/preview/models/{model_id}/log](https://docs.wandb.ai/training/api-reference/models/log-v1-preview-models--model-id--log)** - Log
+- **[POST /v1/preview/models](https://docs.wandb.ai/training/api-reference/models/create-model)** - Create Model
+- **[DELETE /v1/preview/models/{model_id}](https://docs.wandb.ai/training/api-reference/models/delete-model)** - Delete Model
+- **[DELETE /v1/preview/models/{model_id}/checkpoints](https://docs.wandb.ai/training/api-reference/models/delete-model-checkpoints)** - Delete Model Checkpoints
+- **[GET /v1/preview/models/{model_id}/checkpoints](https://docs.wandb.ai/training/api-reference/models/list-model-checkpoints)** - List Model Checkpoints
+- **[POST /v1/preview/models/{model_id}/log](https://docs.wandb.ai/training/api-reference/models/log)** - Log
 
 ### training-jobs
 
-- **[POST /v1/preview/training-jobs](https://docs.wandb.ai/training/api-reference/training-jobs/create-training-job-v1-preview-training-jobs)** - Create Training Job
-- **[GET /v1/preview/training-jobs/{training_job_id}](https://docs.wandb.ai/training/api-reference/training-jobs/get-training-job-v1-preview-training-jobs--training-job-id-)** - Get Training Job
-- **[GET /v1/preview/training-jobs/{training_job_id}/events](https://docs.wandb.ai/training/api-reference/training-jobs/get-training-job-events-v1-preview-training-jobs--training-job-id--events)** - Get Training Job Events
+- **[POST /v1/preview/training-jobs](https://docs.wandb.ai/training/api-reference/training-jobs/create-training-job)** - Create Training Job
+- **[GET /v1/preview/training-jobs/{training_job_id}](https://docs.wandb.ai/training/api-reference/training-jobs/get-training-job)** - Get Training Job
+- **[GET /v1/preview/training-jobs/{training_job_id}/events](https://docs.wandb.ai/training/api-reference/training-jobs/get-training-job-events)** - Get Training Job Events
 
-### Uncategorized
+### health
 
-- **[GET /v1/health](https://docs.wandb.ai/training/api-reference/uncategorized/health-check-v1-health)** - Health Check
-- **[GET /v1/system-check](https://docs.wandb.ai/training/api-reference/uncategorized/system-check-v1-system-check)** - System Check
-### chat-completions
-
-- **[POST /v1/chat/completions](https://docs.wandb.ai/training/api-reference/chat-completions/create-chat-completion-v1-chat-completions)** - Create Chat Completion
-- **[POST /v1/chat/completions/](https://docs.wandb.ai/training/api-reference/chat-completions/create-chat-completion-v1-chat-completions-)** - Create Chat Completion
-
-### models
-
-- **[POST /v1/preview/models](https://docs.wandb.ai/training/api-reference/models/create-model-v1-preview-models)** - Create Model
-- **[DELETE /v1/preview/models/{model_id}/checkpoints](https://docs.wandb.ai/training/api-reference/models/delete-model-checkpoints-v1-preview-models--model-id--checkpoints)** - Delete Model Checkpoints
-- **[GET /v1/preview/models/{model_id}/checkpoints](https://docs.wandb.ai/training/api-reference/models/list-model-checkpoints-v1-preview-models--model-id--checkpoints)** - List Model Checkpoints
-- **[POST /v1/preview/models/{model_id}/log](https://docs.wandb.ai/training/api-reference/models/log-v1-preview-models--model-id--log)** - Log
-
-### training-jobs
-
-- **[POST /v1/preview/training-jobs](https://docs.wandb.ai/training/api-reference/training-jobs/create-training-job-v1-preview-training-jobs)** - Create Training Job
-- **[GET /v1/preview/training-jobs/{training_job_id}](https://docs.wandb.ai/training/api-reference/training-jobs/get-training-job-v1-preview-training-jobs--training-job-id-)** - Get Training Job
-- **[GET /v1/preview/training-jobs/{training_job_id}/events](https://docs.wandb.ai/training/api-reference/training-jobs/get-training-job-events-v1-preview-training-jobs--training-job-id--events)** - Get Training Job Events
-
-### Uncategorized
-
-- **[GET /v1/health](https://docs.wandb.ai/training/api-reference/uncategorized/health-check-v1-health)** - Health Check
-- **[GET /v1/system-check](https://docs.wandb.ai/training/api-reference/uncategorized/system-check-v1-system-check)** - System Check
+- **[GET /v1/health](https://docs.wandb.ai/training/api-reference/health/health-check)** - Health Check
+- **[GET /v1/system-check](https://docs.wandb.ai/training/api-reference/health/system-check)** - System Check
 
 ## Related Resources