Skip to content

Commit becb530

Browse files
mdlinvilledbrian57
mdlinville
and
dbrian57
authored
Weave generated reference improvements (#1889)
## Description Fix Weave generation reference bugs discovered in #1888 - Fix other bugs discovered during testing - Regenerate references in this PR --------- Co-authored-by: Dan Brian <[email protected]>
1 parent 548db50 commit becb530

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+56921
-989
lines changed

‎docs.json‎

Lines changed: 28 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -970,6 +970,14 @@
970970
"pages": [
971971
"weave/reference/python-sdk/trace_server_bindings/remote_http_trace_server"
972972
]
973+
},
974+
{
975+
"group": "Other",
976+
"pages": [
977+
"weave/reference/python-sdk/weave/trace/op",
978+
"weave/reference/python-sdk/weave/trace/weave_client",
979+
"weave/reference/python-sdk/weave/trace_server/trace_server_interface"
980+
]
973981
}
974982
]
975983
},
@@ -980,14 +988,15 @@
980988
{
981989
"group": "Classes",
982990
"pages": [
983-
"weave/reference/typescript-sdk/classes/Dataset",
984-
"weave/reference/typescript-sdk/classes/Evaluation",
985-
"weave/reference/typescript-sdk/classes/EvaluationLogger",
986-
"weave/reference/typescript-sdk/classes/MessagesPrompt",
987-
"weave/reference/typescript-sdk/classes/ScoreLogger",
988-
"weave/reference/typescript-sdk/classes/StringPrompt",
989-
"weave/reference/typescript-sdk/classes/WeaveClient",
990-
"weave/reference/typescript-sdk/classes/WeaveObject"
991+
"weave/reference/typescript-sdk/classes/dataset",
992+
"weave/reference/typescript-sdk/classes/evaluation",
993+
"weave/reference/typescript-sdk/classes/evaluationlogger",
994+
"weave/reference/typescript-sdk/classes/messagesprompt",
995+
"weave/reference/typescript-sdk/classes/objectref",
996+
"weave/reference/typescript-sdk/classes/scorelogger",
997+
"weave/reference/typescript-sdk/classes/stringprompt",
998+
"weave/reference/typescript-sdk/classes/weaveclient",
999+
"weave/reference/typescript-sdk/classes/weaveobject"
9911000
]
9921001
},
9931002
{
@@ -996,27 +1005,27 @@
9961005
"weave/reference/typescript-sdk/functions/init",
9971006
"weave/reference/typescript-sdk/functions/login",
9981007
"weave/reference/typescript-sdk/functions/op",
999-
"weave/reference/typescript-sdk/functions/requireCurrentCallStackEntry",
1000-
"weave/reference/typescript-sdk/functions/requireCurrentChildSummary",
1001-
"weave/reference/typescript-sdk/functions/weaveAudio",
1002-
"weave/reference/typescript-sdk/functions/weaveImage",
1003-
"weave/reference/typescript-sdk/functions/wrapOpenAI"
1008+
"weave/reference/typescript-sdk/functions/requirecurrentcallstackentry",
1009+
"weave/reference/typescript-sdk/functions/requirecurrentchildsummary",
1010+
"weave/reference/typescript-sdk/functions/weaveaudio",
1011+
"weave/reference/typescript-sdk/functions/weaveimage",
1012+
"weave/reference/typescript-sdk/functions/wrapopenai"
10041013
]
10051014
},
10061015
{
10071016
"group": "Interfaces",
10081017
"pages": [
1009-
"weave/reference/typescript-sdk/interfaces/CallSchema",
1010-
"weave/reference/typescript-sdk/interfaces/CallsFilter",
1011-
"weave/reference/typescript-sdk/interfaces/WeaveAudio",
1012-
"weave/reference/typescript-sdk/interfaces/WeaveImage"
1018+
"weave/reference/typescript-sdk/interfaces/callschema",
1019+
"weave/reference/typescript-sdk/interfaces/callsfilter",
1020+
"weave/reference/typescript-sdk/interfaces/weaveaudio",
1021+
"weave/reference/typescript-sdk/interfaces/weaveimage"
10131022
]
10141023
},
10151024
{
10161025
"group": "Type Aliases",
10171026
"pages": [
1018-
"weave/reference/typescript-sdk/type-aliases/Op",
1019-
"weave/reference/typescript-sdk/type-aliases/OpDecorator"
1027+
"weave/reference/typescript-sdk/type-aliases/op",
1028+
"weave/reference/typescript-sdk/type-aliases/opdecorator"
10201029
]
10211030
}
10221031
]

‎scripts/reference-generation/weave/fix_casing.py‎

Lines changed: 24 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -12,108 +12,47 @@
1212
from pathlib import Path
1313

1414
def fix_typescript_casing(base_path):
15-
"""Fix TypeScript SDK file casing."""
16-
print("Fixing TypeScript SDK file casing...")
15+
"""Fix TypeScript SDK file casing - ensure all files use lowercase."""
16+
print("Fixing TypeScript SDK file casing to lowercase...")
1717

18-
ts_base = Path(base_path) / "weave/reference/typescript-sdk/weave"
18+
ts_base = Path(base_path) / "weave/reference/typescript-sdk"
1919
if not ts_base.exists():
2020
print(f" TypeScript SDK path not found: {ts_base}")
2121
return
2222

23-
# Define correct names for each directory
24-
casing_rules = {
25-
"classes": {
26-
"dataset": "Dataset",
27-
"evaluation": "Evaluation",
28-
"weaveclient": "WeaveClient",
29-
"weaveobject": "WeaveObject",
30-
},
31-
"interfaces": {
32-
"callschema": "CallSchema",
33-
"callsfilter": "CallsFilter",
34-
"weaveaudio": "WeaveAudio",
35-
"weaveimage": "WeaveImage",
36-
},
37-
"functions": {
38-
# Functions should be lowercase/camelCase
39-
"init": "init",
40-
"login": "login",
41-
"op": "op",
42-
"requirecurrentcallstackentry": "requireCurrentCallStackEntry",
43-
"requirecurrentchildsummary": "requireCurrentChildSummary",
44-
"weaveaudio": "weaveAudio",
45-
"weaveimage": "weaveImage",
46-
"wrapopenai": "wrapOpenAI",
47-
},
48-
"type-aliases": {
49-
"op": "Op", # Type alias Op is uppercase
50-
"opdecorator": "OpDecorator",
51-
"messagesprompt": "MessagesPrompt",
52-
"stringprompt": "StringPrompt",
53-
}
54-
}
23+
# All TypeScript SDK files should use lowercase filenames for consistency
24+
# This applies to classes, functions, interfaces, and type-aliases
25+
subdirs_to_check = ["classes", "functions", "interfaces", "type-aliases"]
5526

56-
for dir_name, rules in casing_rules.items():
57-
dir_path = ts_base / dir_name
27+
for subdir in subdirs_to_check:
28+
dir_path = ts_base / subdir
5829
if not dir_path.exists():
5930
continue
6031

6132
for file in dir_path.glob("*.mdx"):
62-
basename = file.stem.lower()
63-
if basename in rules:
64-
correct_name = rules[basename]
65-
if file.stem != correct_name:
66-
new_path = file.parent / f"{correct_name}.mdx"
67-
print(f" Renaming: {file.name} → {correct_name}.mdx")
68-
shutil.move(str(file), str(new_path))
33+
# Convert filename to lowercase
34+
lowercase_name = file.stem.lower()
35+
if file.stem != lowercase_name:
36+
new_path = file.parent / f"{lowercase_name}.mdx"
37+
print(f" Renaming: {file.name} → {lowercase_name}.mdx")
38+
shutil.move(str(file), str(new_path))
6939

7040
def fix_python_casing(base_path):
71-
"""Fix Python SDK file casing."""
72-
print("Fixing Python SDK file casing...")
41+
"""Fix Python SDK file casing for WEAVE reference docs only."""
42+
print("Fixing Weave Python SDK file casing...")
7343

74-
py_base = Path(base_path) / "models/ref/python/public-api"
44+
# IMPORTANT: This should ONLY touch Weave reference docs, never Models reference docs
45+
py_base = Path(base_path) / "weave/reference/python-sdk"
7546
if not py_base.exists():
76-
print(f" Python SDK path not found: {py_base}")
47+
print(f" Weave Python SDK path not found: {py_base}")
7748
return
7849

79-
# Python class files that should be uppercase
80-
uppercase_files = {
81-
"artifactcollection": "ArtifactCollection",
82-
"artifactcollections": "ArtifactCollections",
83-
"artifactfiles": "ArtifactFiles",
84-
"artifacttype": "ArtifactType",
85-
"artifacttypes": "ArtifactTypes",
86-
"betareport": "BetaReport",
87-
"file": "File",
88-
"member": "Member",
89-
"project": "Project",
90-
"registry": "Registry",
91-
"run": "Run",
92-
"runartifacts": "RunArtifacts",
93-
"sweep": "Sweep",
94-
"team": "Team",
95-
"user": "User",
96-
}
97-
98-
# Files that should remain lowercase
99-
lowercase_files = ["api", "artifacts", "automations", "files", "projects",
100-
"reports", "runs", "sweeps", "_index"]
50+
# For Weave Python SDK, we generally want lowercase filenames
51+
# Only specific files might need special casing - currently none known
52+
# Most Weave modules use lowercase with underscores (e.g., weave_client.mdx)
10153

102-
for file in py_base.glob("*.mdx"):
103-
basename = file.stem.lower()
104-
105-
if basename in uppercase_files:
106-
correct_name = uppercase_files[basename]
107-
if file.stem != correct_name:
108-
new_path = file.parent / f"{correct_name}.mdx"
109-
print(f" Renaming: {file.name} → {correct_name}.mdx")
110-
shutil.move(str(file), str(new_path))
111-
elif basename in lowercase_files:
112-
# Ensure these stay lowercase
113-
if file.stem != basename:
114-
new_path = file.parent / f"{basename}.mdx"
115-
print(f" Renaming: {file.name} → {basename}.mdx")
116-
shutil.move(str(file), str(new_path))
54+
print(f" Weave Python SDK files are generated with correct casing")
55+
print(f" No casing changes needed for Weave reference documentation")
11756

11857
def main():
11958
"""Main function to fix all casing issues."""

‎scripts/reference-generation/weave/generate_python_sdk_docs.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,10 @@ def generate_module_docs(module, module_name: str, src_root_path: str, version:
255255
# Remove <b>` at the start of lines that don't have a closing </b>
256256
content = re.sub(r'^- <b>`([^`\n]*?)$', r'- \1', content, flags=re.MULTILINE)
257257

258+
# Remove malformed table separators that lazydocs sometimes generates
259+
# These appear as standalone lines with just dashes (------) which break markdown parsing
260+
content = re.sub(r'\n\s*------+\s*\n', '\n\n', content)
261+
258262
# Fix parameter lists that have been broken by lazydocs
259263
# Strategy: Parse all parameters into a structured format, then reconstruct them properly
260264
def fix_parameter_lists(text):

‎scripts/reference-generation/weave/generate_python_sdk_minimal.py‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,44 @@ def install_weave(version="latest"):
2424

2525

2626
def get_docstring(obj):
27-
"""Extract and format docstring."""
27+
"""Extract and format docstring for MDX compatibility."""
28+
import re
29+
2830
doc = inspect.getdoc(obj)
29-
return doc if doc else "No description available."
31+
if not doc:
32+
return "No description available."
33+
34+
# Remove Pydantic documentation links that reference non-existent concept pages
35+
# These come from Pydantic's own docstrings and aren't relevant for our docs
36+
# Pattern: [text](../concepts/anything.md) or similar concept page links
37+
doc = re.sub(r'\[([^\]]+)\]\(\.\./concepts/[^\)]+\)', r'\1', doc)
38+
doc = re.sub(r'\[([^\]]+)\]\(\./concepts/[^\)]+\)', r'\1', doc)
39+
doc = re.sub(r'\[([^\]]+)\]\(concepts/[^\)]+\)', r'\1', doc)
40+
41+
# Remove "Usage Documentation" admonition blocks that contain broken links
42+
doc = re.sub(r'!!! abstract "Usage Documentation"\s+\[`[^`]+`\]\([^\)]+\)\s*\n\s*\n', '', doc)
43+
44+
# Escape curly braces for MDX (they're interpreted as JSX expressions)
45+
# We need to be careful to only escape braces that aren't in code blocks
46+
lines = doc.split('\n')
47+
result_lines = []
48+
in_code_block = False
49+
50+
for line in lines:
51+
# Check if this is a code block marker (triple backticks or indented code after ::)
52+
if line.strip().startswith('```'):
53+
in_code_block = not in_code_block
54+
result_lines.append(line)
55+
elif not in_code_block:
56+
# Escape curly braces outside of code blocks
57+
# Replace { with \{ and } with \}
58+
line = line.replace('{', '\\{').replace('}', '\\}')
59+
result_lines.append(line)
60+
else:
61+
# Inside code block, keep as-is
62+
result_lines.append(line)
63+
64+
return '\n'.join(result_lines)
3065

3166

3267
def get_function_signature(func):

‎scripts/reference-generation/weave/generate_service_api_spec.py‎

Lines changed: 8 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -12,59 +12,19 @@
1212
def main():
1313
"""Main function."""
1414
print("Service API configuration:")
15-
print(" Using remote OpenAPI spec: https://trace.wandb.ai/openapi.json")
16-
print(" Mintlify will generate documentation for all 41 endpoints")
15+
print(" Using OpenAPI spec from sync_openapi_spec.py")
16+
print(" Mintlify will generate documentation for endpoints")
1717
print("")
1818

19-
# Create the service-api directory structure
19+
# Create the service-api directory structure for openapi.json
20+
# Note: The landing page is service-api.mdx (not service-api/index.mdx)
21+
# and is managed by update_service_api_landing.py
2022
service_api_dir = Path("weave/reference/service-api")
2123
service_api_dir.mkdir(parents=True, exist_ok=True)
2224

23-
# Create an index file if it doesn't exist
24-
index_file = service_api_dir / "index.mdx"
25-
if not index_file.exists():
26-
index_content = """---
27-
title: "Service API"
28-
description: "REST API endpoints for the Weave service"
29-
---
30-
31-
# Weave Service API
32-
33-
The Weave Service API provides REST endpoints for interacting with the Weave tracing service.
34-
35-
## Available Endpoints
36-
37-
This documentation is automatically generated from the OpenAPI specification at https://trace.wandb.ai/openapi.json.
38-
39-
The API includes endpoints for:
40-
- **Calls**: Start, end, update, query, and manage traces
41-
- **Tables**: Create, update, and query data tables
42-
- **Files**: Upload and manage file attachments
43-
- **Objects**: Store and retrieve versioned objects
44-
- **Feedback**: Collect and query user feedback
45-
- **Costs**: Track and query usage costs
46-
- **Inference**: OpenAI-compatible inference endpoints
47-
48-
## Authentication
49-
50-
Most endpoints require authentication. Include your W&B API key in the request headers:
51-
52-
```
53-
Authorization: Bearer YOUR_API_KEY
54-
```
55-
56-
## Base URL
57-
58-
All API requests should be made to:
59-
60-
```
61-
https://trace.wandb.ai
62-
```
63-
"""
64-
index_file.write_text(index_content)
65-
print(f"✓ Created Service API index at {index_file}")
66-
67-
print("✓ Service API setup complete!")
25+
print("✓ Service API directory structure ready")
26+
print(" Note: Landing page at weave/reference/service-api.mdx")
27+
print(" Note: OpenAPI spec at weave/reference/service-api/openapi.json")
6828

6929

7030
if __name__ == "__main__":

0 commit comments

Comments
 (0)