Weave generated reference improvements

docs.json

@@ -961,6 +961,14 @@
                         "pages": [
                           "weave/reference/python-sdk/trace_server_bindings/remote_http_trace_server"
                         ]
+                      },
+                      {
+                        "group": "Other",
+                        "pages": [
+                          "weave/reference/python-sdk/weave/trace/op",
+                          "weave/reference/python-sdk/weave/trace/weave_client",
+                          "weave/reference/python-sdk/weave/trace_server/trace_server_interface"
+                        ]
                       }
                     ]
                   },
@@ -971,14 +979,15 @@
                       {
                         "group": "Classes",
                         "pages": [
-                          "weave/reference/typescript-sdk/classes/Dataset",
-                          "weave/reference/typescript-sdk/classes/Evaluation",
-                          "weave/reference/typescript-sdk/classes/EvaluationLogger",
-                          "weave/reference/typescript-sdk/classes/MessagesPrompt",
-                          "weave/reference/typescript-sdk/classes/ScoreLogger",
-                          "weave/reference/typescript-sdk/classes/StringPrompt",
-                          "weave/reference/typescript-sdk/classes/WeaveClient",
-                          "weave/reference/typescript-sdk/classes/WeaveObject"
+                          "weave/reference/typescript-sdk/classes/dataset",
+                          "weave/reference/typescript-sdk/classes/evaluation",
+                          "weave/reference/typescript-sdk/classes/evaluationlogger",
+                          "weave/reference/typescript-sdk/classes/messagesprompt",
+                          "weave/reference/typescript-sdk/classes/objectref",
+                          "weave/reference/typescript-sdk/classes/scorelogger",
+                          "weave/reference/typescript-sdk/classes/stringprompt",
+                          "weave/reference/typescript-sdk/classes/weaveclient",
+                          "weave/reference/typescript-sdk/classes/weaveobject"
                         ]
                       },
                       {
@@ -987,27 +996,27 @@
                           "weave/reference/typescript-sdk/functions/init",
                           "weave/reference/typescript-sdk/functions/login",
                           "weave/reference/typescript-sdk/functions/op",
-                          "weave/reference/typescript-sdk/functions/requireCurrentCallStackEntry",
-                          "weave/reference/typescript-sdk/functions/requireCurrentChildSummary",
-                          "weave/reference/typescript-sdk/functions/weaveAudio",
-                          "weave/reference/typescript-sdk/functions/weaveImage",
-                          "weave/reference/typescript-sdk/functions/wrapOpenAI"
+                          "weave/reference/typescript-sdk/functions/requirecurrentcallstackentry",
+                          "weave/reference/typescript-sdk/functions/requirecurrentchildsummary",
+                          "weave/reference/typescript-sdk/functions/weaveaudio",
+                          "weave/reference/typescript-sdk/functions/weaveimage",
+                          "weave/reference/typescript-sdk/functions/wrapopenai"
                         ]
                       },
                       {
                         "group": "Interfaces",
                         "pages": [
-                          "weave/reference/typescript-sdk/interfaces/CallSchema",
-                          "weave/reference/typescript-sdk/interfaces/CallsFilter",
-                          "weave/reference/typescript-sdk/interfaces/WeaveAudio",
-                          "weave/reference/typescript-sdk/interfaces/WeaveImage"
+                          "weave/reference/typescript-sdk/interfaces/callschema",
+                          "weave/reference/typescript-sdk/interfaces/callsfilter",
+                          "weave/reference/typescript-sdk/interfaces/weaveaudio",
+                          "weave/reference/typescript-sdk/interfaces/weaveimage"
                         ]
                       },
                       {
                         "group": "Type Aliases",
                         "pages": [
-                          "weave/reference/typescript-sdk/type-aliases/Op",
-                          "weave/reference/typescript-sdk/type-aliases/OpDecorator"
+                          "weave/reference/typescript-sdk/type-aliases/op",
+                          "weave/reference/typescript-sdk/type-aliases/opdecorator"
                         ]
                       }
                     ]

scripts/reference-generation/weave/fix_casing.py

@@ -12,108 +12,47 @@
 from pathlib import Path
 
 def fix_typescript_casing(base_path):
-    """Fix TypeScript SDK file casing."""
-    print("Fixing TypeScript SDK file casing...")
+    """Fix TypeScript SDK file casing - ensure all files use lowercase."""
+    print("Fixing TypeScript SDK file casing to lowercase...")
 
-    ts_base = Path(base_path) / "weave/reference/typescript-sdk/weave"
+    ts_base = Path(base_path) / "weave/reference/typescript-sdk"
     if not ts_base.exists():
         print(f"  TypeScript SDK path not found: {ts_base}")
         return
 
-    # Define correct names for each directory
-    casing_rules = {
-        "classes": {
-            "dataset": "Dataset",
-            "evaluation": "Evaluation", 
-            "weaveclient": "WeaveClient",
-            "weaveobject": "WeaveObject",
-        },
-        "interfaces": {
-            "callschema": "CallSchema",
-            "callsfilter": "CallsFilter",
-            "weaveaudio": "WeaveAudio",
-            "weaveimage": "WeaveImage",
-        },
-        "functions": {
-            # Functions should be lowercase/camelCase
-            "init": "init",
-            "login": "login",
-            "op": "op",
-            "requirecurrentcallstackentry": "requireCurrentCallStackEntry",
-            "requirecurrentchildsummary": "requireCurrentChildSummary",
-            "weaveaudio": "weaveAudio",
-            "weaveimage": "weaveImage",
-            "wrapopenai": "wrapOpenAI",
-        },
-        "type-aliases": {
-            "op": "Op",  # Type alias Op is uppercase
-            "opdecorator": "OpDecorator",
-            "messagesprompt": "MessagesPrompt",
-            "stringprompt": "StringPrompt",
-        }
-    }
+    # All TypeScript SDK files should use lowercase filenames for consistency
+    # This applies to classes, functions, interfaces, and type-aliases
+    subdirs_to_check = ["classes", "functions", "interfaces", "type-aliases"]
 
-    for dir_name, rules in casing_rules.items():
-        dir_path = ts_base / dir_name
+    for subdir in subdirs_to_check:
+        dir_path = ts_base / subdir
         if not dir_path.exists():
             continue
 
         for file in dir_path.glob("*.mdx"):
-            basename = file.stem.lower()
-            if basename in rules:
-                correct_name = rules[basename]
-                if file.stem != correct_name:
-                    new_path = file.parent / f"{correct_name}.mdx"
-                    print(f"  Renaming: {file.name} → {correct_name}.mdx")
-                    shutil.move(str(file), str(new_path))
+            # Convert filename to lowercase
+            lowercase_name = file.stem.lower()
+            if file.stem != lowercase_name:
+                new_path = file.parent / f"{lowercase_name}.mdx"
+                print(f"  Renaming: {file.name} → {lowercase_name}.mdx")
+                shutil.move(str(file), str(new_path))
 
 def fix_python_casing(base_path):
-    """Fix Python SDK file casing."""
-    print("Fixing Python SDK file casing...")
+    """Fix Python SDK file casing for WEAVE reference docs only."""
+    print("Fixing Weave Python SDK file casing...")
 
-    py_base = Path(base_path) / "models/ref/python/public-api"
+    # IMPORTANT: This should ONLY touch Weave reference docs, never Models reference docs
+    py_base = Path(base_path) / "weave/reference/python-sdk"
     if not py_base.exists():
-        print(f"  Python SDK path not found: {py_base}")
+        print(f"  Weave Python SDK path not found: {py_base}")
         return
 
-    # Python class files that should be uppercase
-    uppercase_files = {
-        "artifactcollection": "ArtifactCollection",
-        "artifactcollections": "ArtifactCollections",
-        "artifactfiles": "ArtifactFiles",
-        "artifacttype": "ArtifactType",
-        "artifacttypes": "ArtifactTypes",
-        "betareport": "BetaReport",
-        "file": "File",
-        "member": "Member",
-        "project": "Project",
-        "registry": "Registry",
-        "run": "Run",
-        "runartifacts": "RunArtifacts",
-        "sweep": "Sweep",
-        "team": "Team",
-        "user": "User",
-    }
-
-    # Files that should remain lowercase
-    lowercase_files = ["api", "artifacts", "automations", "files", "projects", 
-                       "reports", "runs", "sweeps", "_index"]
+    # For Weave Python SDK, we generally want lowercase filenames
+    # Only specific files might need special casing - currently none known
+    # Most Weave modules use lowercase with underscores (e.g., weave_client.mdx)
 
-    for file in py_base.glob("*.mdx"):
-        basename = file.stem.lower()
-
-        if basename in uppercase_files:
-            correct_name = uppercase_files[basename]
-            if file.stem != correct_name:
-                new_path = file.parent / f"{correct_name}.mdx"
-                print(f"  Renaming: {file.name} → {correct_name}.mdx")
-                shutil.move(str(file), str(new_path))
-        elif basename in lowercase_files:
-            # Ensure these stay lowercase
-            if file.stem != basename:
-                new_path = file.parent / f"{basename}.mdx"
-                print(f"  Renaming: {file.name} → {basename}.mdx")
-                shutil.move(str(file), str(new_path))
+    print(f"  Weave Python SDK files are generated with correct casing")
+    print(f"  No casing changes needed for Weave reference documentation")
 
 def main():
     """Main function to fix all casing issues."""

scripts/reference-generation/weave/generate_python_sdk_docs.py

@@ -255,6 +255,10 @@ def generate_module_docs(module, module_name: str, src_root_path: str, version:
     # Remove <b>` at the start of lines that don't have a closing </b>
     content = re.sub(r'^- <b>`([^`\n]*?)$', r'- \1', content, flags=re.MULTILINE)
 
+    # Remove malformed table separators that lazydocs sometimes generates
+    # These appear as standalone lines with just dashes (------) which break markdown parsing
+    content = re.sub(r'\n\s*------+\s*\n', '\n\n', content)
+
     # Fix parameter lists that have been broken by lazydocs
     # Strategy: Parse all parameters into a structured format, then reconstruct them properly
     def fix_parameter_lists(text):

scripts/reference-generation/weave/generate_python_sdk_minimal.py

@@ -24,9 +24,44 @@ def install_weave(version="latest"):
 
 
 def get_docstring(obj):
-    """Extract and format docstring."""
+    """Extract and format docstring for MDX compatibility."""
+    import re
+
     doc = inspect.getdoc(obj)
-    return doc if doc else "No description available."
+    if not doc:
+        return "No description available."
+
+    # Remove Pydantic documentation links that reference non-existent concept pages
+    # These come from Pydantic's own docstrings and aren't relevant for our docs
+    # Pattern: [text](../concepts/anything.md) or similar concept page links
+    doc = re.sub(r'\[([^\]]+)\]\(\.\./concepts/[^\)]+\)', r'\1', doc)
+    doc = re.sub(r'\[([^\]]+)\]\(\./concepts/[^\)]+\)', r'\1', doc)
+    doc = re.sub(r'\[([^\]]+)\]\(concepts/[^\)]+\)', r'\1', doc)
+
+    # Remove "Usage Documentation" admonition blocks that contain broken links
+    doc = re.sub(r'!!! abstract "Usage Documentation"\s+\[`[^`]+`\]\([^\)]+\)\s*\n\s*\n', '', doc)
+
+    # Escape curly braces for MDX (they're interpreted as JSX expressions)
+    # We need to be careful to only escape braces that aren't in code blocks
+    lines = doc.split('\n')
+    result_lines = []
+    in_code_block = False
+
+    for line in lines:
+        # Check if this is a code block marker (triple backticks or indented code after ::)
+        if line.strip().startswith('```'):
+            in_code_block = not in_code_block
+            result_lines.append(line)
+        elif not in_code_block:
+            # Escape curly braces outside of code blocks
+            # Replace { with \{ and } with \}
+            line = line.replace('{', '\\{').replace('}', '\\}')
+            result_lines.append(line)
+        else:
+            # Inside code block, keep as-is
+            result_lines.append(line)
+
+    return '\n'.join(result_lines)
 
 
 def get_function_signature(func):

scripts/reference-generation/weave/generate_service_api_spec.py

@@ -12,59 +12,19 @@
 def main():
     """Main function."""
     print("Service API configuration:")
-    print("  Using remote OpenAPI spec: https://trace.wandb.ai/openapi.json")
-    print("  Mintlify will generate documentation for all 41 endpoints")
+    print("  Using OpenAPI spec from sync_openapi_spec.py")
+    print("  Mintlify will generate documentation for endpoints")
     print("")
 
-    # Create the service-api directory structure
+    # Create the service-api directory structure for openapi.json
+    # Note: The landing page is service-api.mdx (not service-api/index.mdx)
+    # and is managed by update_service_api_landing.py
     service_api_dir = Path("weave/reference/service-api")
     service_api_dir.mkdir(parents=True, exist_ok=True)
 
-    # Create an index file if it doesn't exist
-    index_file = service_api_dir / "index.mdx"
-    if not index_file.exists():
-        index_content = """---
-title: "Service API"
-description: "REST API endpoints for the Weave service"
----
-
-# Weave Service API
-
-The Weave Service API provides REST endpoints for interacting with the Weave tracing service.
-
-## Available Endpoints
-
-This documentation is automatically generated from the OpenAPI specification at https://trace.wandb.ai/openapi.json.
-
-The API includes endpoints for:
-- **Calls**: Start, end, update, query, and manage traces
-- **Tables**: Create, update, and query data tables
-- **Files**: Upload and manage file attachments
-- **Objects**: Store and retrieve versioned objects
-- **Feedback**: Collect and query user feedback
-- **Costs**: Track and query usage costs
-- **Inference**: OpenAI-compatible inference endpoints
-
-## Authentication
-
-Most endpoints require authentication. Include your W&B API key in the request headers:
-
-```
-Authorization: Bearer YOUR_API_KEY
-```
-
-## Base URL
-
-All API requests should be made to:
-
-```
-https://trace.wandb.ai
-```
-"""
-        index_file.write_text(index_content)
-        print(f"✓ Created Service API index at {index_file}")
-
-    print("✓ Service API setup complete!")
+    print("✓ Service API directory structure ready")
+    print("  Note: Landing page at weave/reference/service-api.mdx")
+    print("  Note: OpenAPI spec at weave/reference/service-api/openapi.json")
 
 
 if __name__ == "__main__":