# AUTO-GENERATED FILE - DO NOT EDIT

# This file was automatically generated by the XDK build tool.

# Any manual changes will be overwritten on the next generation.

#!/usr/bin/env python3

"""

AUTO-GENERATED FILE - DO NOT EDIT

This file was automatically generated by the XDK build tool.

Any manual changes will be overwritten on the next generation.

Process Sphinx-generated markdown documentation for Mintlify.

"""

import os

import sys

import json

import re

import shutil

from pathlib import Path

from typing import Dict, List, Optional, Set

print("🚀 Processing X API SDK Documentation for Mintlify...")

# Mintlify configuration

MINTLIFY_CONFIG = {

"outputDir": "mintlify-docs",

"baseUrl": "https://docs.x.com",

"title": "X API SDK v0.4.6",

"description": "Python SDK for the X API with comprehensive pagination, authentication, and streaming support.",

"version": "0.4.6",

"githubUrl": "https://github.com/xdevplatform/xdk",

}

def clean_title(title: str, file_path: str = "", content: str = "") -> str:

"""Clean and improve title formatting."""

if not isinstance(title, str):

title = str(title)

# Try to extract class name from content first (more reliable)

if content:

# Look for class definition: ### *class* xdk.module.ClassName

class_match = re.search(

r"\*class\*\s+[^\s]*\.([A-Z][a-zA-Z0-9_]*Client|Client|Paginator|OAuth2PKCEAuth)\b",

content,

)

if class_match:

return class_match.group(1)

# Remove module suffix

title = re.sub(r"\s+module\s*$", "", title, flags=re.IGNORECASE)

# Extract class name from patterns like "xdk.users.client.UsersClient"

class_match = re.search(

r"\.([A-Z][a-zA-Z0-9_]+Client|Paginator|OAuth2PKCEAuth)\b", title

)

if class_match:

return class_match.group(1)

# Fallback to generic Client only if no specific client found

if "Client" in title and not re.search(r"[A-Z][a-zA-Z0-9_]+Client", title):

class_match = re.search(r"\.(Client)\b", title)

if class_match:

return class_match.group(1)

# Extract class name from patterns like "*class* xdk.users.client.UsersClient"

class_match2 = re.search(

r"\*class\*\s+[^\s]*\.([A-Z][a-zA-Z0-9_]*Client|Client|Paginator|OAuth2PKCEAuth)\b",

title,

)

if class_match2:

return class_match2.group(1)

# Remove xdk. prefix

title = re.sub(r"^xdk\.", "", title)

# Convert snake_case to PascalCase for module names

if "." in title and not title[0].isupper():

parts = title.split(".")

# Capitalize each part

title = ".".join(p.capitalize() for p in parts)

# Clean up

title = (

re.sub(r"<.*?>", "", title) # Remove generic type parameters

.replace("Class: ", "")

.replace("Interface: ", "")

.replace("*class*", "")

.replace("*", "")

.replace("\\", "")

.replace("\n", " ")

.strip()

)

return title

def generate_frontmatter(

title: str, sidebar_title: Optional[str] = None, file_path: str = ""

) -> str:

"""Generate Mintlify frontmatter."""

cleaned_title = clean_title(title, file_path)

cleaned_sidebar = (

clean_title(sidebar_title, file_path) if sidebar_title else cleaned_title

)

frontmatter = f'title: "{cleaned_title}"\n'

if sidebar_title:

frontmatter += f'sidebarTitle: "{cleaned_sidebar}"\n'

return f"---\n{frontmatter}---\n\n"

def reorganize_class_structure(content: str, file_path: str) -> str:

"""Reorganize content into proper sections like TypeScript."""

# Check if this is a class/client file

if "client" not in file_path.lower() and "models" not in file_path.lower():

return content

# Find class definition - handle both formats

# Pattern 1: ### *class* xdk.module.ClassName(params)

# Pattern 2: ### `*class* xdk.module.ClassName`(params)

class_match = re.search(

r"###\s+(?:`?)?\*class\*\s+([^\n(]+)(?:`?)?\s*\(([^)]*)\)", content

)

if not class_match:

return content

class_name_full = class_match.group(1).strip().replace("*", "").replace("`", "")

# Extract just the class name (last part after last dot)

class_name = (

class_name_full.split(".")[-1] if "." in class_name_full else class_name_full

)

class_params = class_match.group(2).strip()

# Extract description after class definition

class_start = class_match.end()

next_section = content.find("###", class_start)

if next_section == -1:

next_section = len(content)

description = content[class_start:next_section].strip()

# Extract "Bases:" line for later use as Badge

bases_match = re.search(r"Bases:\s*`([^`]+)`", description, re.IGNORECASE)

bases = bases_match.group(1).strip() if bases_match else None

# Remove "Bases:" line - we'll add it as a Badge

description = re.sub(

r"Bases:\s*`[^`]+`\s*\n?", "", description, flags=re.IGNORECASE

)

# Remove any stray closing parentheses

description = re.sub(r"^\)\s*\n?", "", description)

description = description.strip()

# Find all methods and properties

methods = []

constructors = []

properties = []

# Pattern for methods: ### method_name(params) → ReturnType

method_pattern = r"###\s+`?([^\n(]+)`?\s*\(([^)]*)\)(?:\s*→\s*([^\n]+))?"

for match in re.finditer(method_pattern, content):

method_name = (

match.group(1).strip().replace("`", "").replace("\\", "").replace("*", "")

)

params = match.group(2).strip()

return_type = match.group(3).strip() if match.group(3) else None

# Find method body

method_start = match.start()

next_method = content.find("###", method_start + 1)

if next_method == -1:

method_body = content[method_start:]

else:

method_body = content[method_start:next_method]

method_info = {

"name": method_name,

"params": params,

"return_type": return_type,

"body": method_body,

}

if method_name == "__init__" or "constructor" in method_name.lower():

constructors.append(method_info)

elif method_name.startswith("property") or "property" in method_body.lower():

properties.append(method_info)

else:

methods.append(method_info)

# Rebuild content with proper sections

sections = []

# Class definition and description

sections.append(f"## {class_name}\n\n")

sections.append('<Badge color="blue">Class</Badge>\n')

if bases:

sections.append(f'\n<Badge color="gray">Bases: {bases}</Badge>\n')

if description:

sections.append(f"\n{description}\n")

# Constructors section

if constructors:

sections.append("\n## Constructors\n")

for const in constructors:

sections.append(const["body"])

# Methods section

if methods:

sections.append("\n## Methods\n")

for method in methods:

sections.append(method["body"])

# Properties section

if properties:

sections.append("\n## Properties\n")

for prop in properties:

sections.append(prop["body"])

# If we found methods/constructors, rebuild content

if constructors or methods or properties:

before_class = content[: class_match.start()]

# Get remaining content after last method

if methods:

last_method_end = content.rfind(methods[-1]["body"])

remaining = content[last_method_end + len(methods[-1]["body"]) :]

elif constructors:

last_constructor_end = content.rfind(constructors[-1]["body"])

remaining = content[last_constructor_end + len(constructors[-1]["body"]) :]

else:

remaining = content[next_section:]

# Clean up any stray characters and duplicate class definitions

remaining = re.sub(r"^\)\s*\n", "", remaining)

# Remove duplicate class definitions that might have been left behind

# Pattern: ### `class xdk.module.ClassName` followed by description and parameters

# Match the full duplicate class definition block

remaining = re.sub(

r"###\s+`?class\s+xdk\.[^\n]+\n\n[^\n]+\n\n(?:####\s+Parameters[^\n]+\n\n<ParamField[^>]+>\s*</ParamField>\s*\n)?",

"",

remaining,

)

# Also remove any standalone class definitions without parameters

remaining = re.sub(

r"###\s+`?\*?class\*?\s+xdk\.[^\n]+\n\n[^\n]+\n\n", "", remaining

)

# Remove any remaining class definition patterns (more aggressive)

remaining = re.sub(

r"###\s+`?class\s+[^\n]+\n\n[^\n]+\n\n(?:####\s+Parameters[^\n]+\n\n)?",

"",

remaining,

)

return before_class + "\n".join(sections) + remaining

return content

def clean_class_definitions(content: str) -> str:

"""Clean up class definition headers."""

# Remove any remaining class definition headers that weren't processed

# Pattern: ### `*class* xdk.module.ClassName`(params) or ## xdk.module.ClassName

# These should already be converted by reorganize_class_structure, but clean up any leftovers

# Remove any stray class definition patterns

content = re.sub(r"##\s+xdk\.[^\n]+\n\n\)\s*\n", "", content)

# Clean up any remaining "Bases:" lines that weren't converted

content = re.sub(r"^Bases:\s*`[^`]+`\s*\n?", "", content, flags=re.MULTILINE)

return content

def fix_method_names(content: str) -> str:

"""Fix method names with escaped underscores."""

# Pattern: ### ``\_\_init_\_`` -> ### `__init__`

# Handle double backticks with escaped underscores

content = re.sub(r"###\s+``\\?(_+[^`]+_+)``", r"### `\1`", content)

# Pattern: ### ``method\_name`` -> ### `method_name`

content = re.sub(r"###\s+``([^`]*)\\?(_[^`]*)``", r"### `\1\2`", content)

# Pattern: ### ``\_\_init_\_``(params) -> ### `__init__`(params)

content = re.sub(r"###\s+``([^`]*)\\?(_[^`]*)``\s*\(", r"### `\1\2`(", content)

# Remove any remaining escaped underscores in method names (single backticks)

content = re.sub(r"###\s+`([^`]*)\\?(_[^`]*)`\s*\(", r"### `\1\2`(", content)

# Fix any remaining escaped underscores in code blocks

content = re.sub(r"`([^`]*)\\?(_[^`]*)`", r"`\1\2`", content)

return content

def improve_method_formatting(content: str) -> str:

"""Improve method formatting to match TypeScript style with ParamField components."""

# Pattern: ### method_name(params) → ReturnType

def convert_method(match):

method_header = match.group(0)

method_name = (

match.group(1)

.strip()

.replace("*", "")

.replace("`", "")

.replace("\\", "")

.replace("_", "_")

)

params_str = match.group(2).strip() if match.group(2) else ""

return_type = match.group(3).strip() if match.group(3) else None

# Find method body (until next ### or ####)

method_start = match.start()

next_method = content.find("###", method_start + 1)

if next_method == -1:

method_body = content[method_start:]

else:

method_body = content[method_start:next_method]

# Extract description (text after method header, before :param)

desc_match = re.search(

r"###[^\n]+\n\n([^\n]+(?:\n(?!:param|####|###|####)[^\n]+)*)",

method_body,

re.MULTILINE,

)

description = desc_match.group(1).strip() if desc_match else ""

# Remove method name from description if it appears

description = re.sub(

r"^" + re.escape(method_name) + r"\s*$", "", description, flags=re.MULTILINE

).strip()

# Parse parameters and convert to ParamField components

param_fields = []

if params_str:

# Simple parameter parsing (split by comma, but handle type annotations)

params = []

current = ""

depth = 0

for char in params_str:

if char in "[(":

depth += 1

elif char in "])":

depth -= 1

elif char == "," and depth == 0:

if current.strip():

params.append(current.strip())

current = ""

continue

current += char

if current.strip():

params.append(current.strip())

for param in params:

# Parse: name: type = default

# Handle cases like: client: [Client](xdk.md#xdk.Client)

param_match = re.match(

r"(\w+)(?:\s*:\s*([^=]+))?(?:\s*=\s*(.+))?$", param.strip()

)

if param_match:

param_name = param_match.group(1)

param_type_raw = (

param_match.group(2).strip() if param_match.group(2) else "Any"

)

param_default = (

param_match.group(3).strip() if param_match.group(3) else None

)

# Clean type - handle markdown links first

# Pattern: [Type](path#anchor) -> extract just "Type"

link_match = re.search(r"\[([^\]]+)\]\(([^\)]+)\)", param_type_raw)

if link_match:

param_type = link_match.group(1) # Use just the link text

else:

# No link, use the raw type but clean it

param_type = param_type_raw

# Remove file references and anchors

param_type = re.sub(r"[a-z_]+\.(md|py)#[^\s]*", "", param_type)

param_type = re.sub(r"#[^\s]*", "", param_type)

# Remove incomplete link patterns like "Client]("

param_type = re.sub(r"\]\([^\)]*$", "", param_type)

param_type = re.sub(r"\]\([^\)]*\)", "", param_type)

# Clean up the type string

param_type = param_type.replace("|", " or ").strip()

# Remove any trailing/leading brackets and parentheses

param_type = re.sub(r"^[\[\(]+", "", param_type)

param_type = re.sub(r"[\]\)]+$", "", param_type)

# Remove any remaining incomplete patterns

param_type = re.sub(r"\]\(.*$", "", param_type)

# Escape angle brackets for MDX

param_type = param_type.replace("<", "&lt;").replace(">", "&gt;")

# Clean up extra spaces

param_type = re.sub(r"\s+", " ", param_type).strip()

# If type is empty or just brackets, default to Any

if not param_type or param_type in ["[", "]", "()", "(", ")", "]("]:

param_type = "Any"

# Find param description

param_desc_match = re.search(

rf":param\s+{param_name}:\s*([^\n]+)", method_body

)

param_desc = (

param_desc_match.group(1).strip() if param_desc_match else ""

)

# Build ParamField - use path instead of name

# For Python methods, parameters are function arguments

# Use "path" location for most parameters, or "body" if it's clearly a request body

param_location = (

"body"

if param_name.lower() in ["body", "data", "payload", "request"]

else "path"

)

param_field = f'<ParamField path="{param_location}.{param_name}" type="{param_type}"'

if param_default:

# Escape default value

param_default_clean = (

param_default.replace('"', "&quot;")

.replace("<", "&lt;")

.replace(">", "&gt;")

)

param_field += f' default="{param_default_clean}"'

param_field += ">"

if param_desc:

param_field += f"\n{param_desc}\n"

param_field += "</ParamField>"

param_fields.append(param_field)

# Build new method format

new_method = f"### `{method_name}`\n\n"

if description:

new_method += f"{description}\n\n"

if param_fields:

new_method += "#### Parameters\n\n"

new_method += "\n\n".join(param_fields) + "\n\n"

if return_type:

# Extract return description

return_desc_match = re.search(r":param\s+Returns?:\s*([^\n]+)", method_body)

return_desc = (

return_desc_match.group(1).strip() if return_desc_match else ""

)

# Clean return type - handle markdown links

return_type_clean = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", return_type)

return_type_clean = re.sub(

r"[a-z_]+\.(md|py)#[^\s]+", "", return_type_clean

)

return_type_clean = return_type_clean.replace("[", "").replace("]", "")

return_type_clean = return_type_clean.replace("<", "&lt;").replace(

">", "&gt;"

)

return_type_clean = re.sub(

r":param\s+\w+:\s*", "", return_type_clean

).strip()

return_type_clean = re.sub(r"\s+", " ", return_type_clean).strip()

new_method += "#### Returns\n\n"

new_method += f"`{return_type_clean}`"

if return_desc and return_desc != return_type_clean:

new_method += f" - {return_desc}"

new_method += "\n\n"

return new_method

# Convert method signatures to use ParamField components

# Match: ### method_name(params) → ReturnType

def process_all_methods(text):

# Find all method definitions

method_pattern = r"###\s+`?([^\n(]+)`?\s*\(([^)]*)\)(?:\s*→\s*([^\n]+))?"

methods = list(re.finditer(method_pattern, text, re.MULTILINE))

if not methods:

return text

# Build result by processing each method and replacing its entire section

result_parts = []

last_pos = 0

for i, match in enumerate(methods):

# Add content before this method

result_parts.append(text[last_pos : match.start()])

# Find where this method's body ends (next method or end of content)

method_start = match.start()

if i + 1 < len(methods):

next_method_start = methods[i + 1].start()

else:

next_method_start = len(text)

# Get the full method section to replace

method_section = text[method_start:next_method_start]

# Convert this method

converted = convert_method(match)

# Remove the old method content from the section

result_parts.append(converted)

last_pos = next_method_start

# Add remaining content

result_parts.append(text[last_pos:])

return "".join(result_parts)

content = process_all_methods(content)

# Clean up any remaining :param lines that weren't converted

content = re.sub(r":param\s+(\w+):\s*([^\n]+)", r"**`\1`** - \2", content)

content = re.sub(r":param\s+Returns?:\s*([^\n]+)", r"**Returns:** \1", content)

# Remove duplicate return descriptions

content = re.sub(

r"(#### Returns\n\n`[^\n]+`[^\n]+\n\n)(\*\*`[^\n]+\*\*[^\n]+\n)+",

r"\1",

content,

)

# Remove duplicate method descriptions

content = re.sub(r"(### `[^\n]+`\n\n[^\n]+\n\n[^\n]+\n\n)(\1)", r"\1", content)

# Clean up any remaining old format parameter lines after ParamField sections

content = re.sub(r"(</ParamField>\n\n)(\*\*`[^\n]+\*\*[^\n]+\n)+", r"\1", content)

# Remove duplicate "Returns:" text in return sections

content = re.sub(

r"(#### Returns\n\n`[^\n]+`)\s*-\s*\*\*`[^\n]+\*\*\s*-\s*([^\n]+)",

r"\1 - \2",

content,

)

# Remove duplicate class definitions that appear after the main class header

# Pattern: ### `class xdk.module.ClassName` followed by description and parameters

# Find the main class header (should be ## ClassName)

main_class_match = re.search(

r"##\s+([A-Z][a-zA-Z0-9_]+Client|Client|Paginator|OAuth2PKCEAuth|BaseModel)",

content,

)

if main_class_match:

# Everything after the main class header should not have duplicate class definitions

before_main = content[: main_class_match.end()]

after_main = content[main_class_match.end() :]

# Remove any class definitions from after_main

after_main = re.sub(

r"###\s+`?class\s+xdk\.[^\n]+\n\n[^\n]+\n\n(?:####\s+Parameters[^\n]+\n\n<ParamField[^>]+>\s*</ParamField>\s*\n)?",

"",

after_main,

)

content = before_main + after_main

# Remove duplicate parameter sections (#### Parameters appearing twice in a row)

content = re.sub(

r"(#### Parameters\n\n<ParamField[^>]+>\s*</ParamField>\s*\n)\1", r"\1", content

)

return content

def convert_method(match):

method_header = match.group(0)

method_name = (

match.group(1)

.strip()

.replace("*", "")

.replace("`", "")

.replace("\\", "")

.replace("_", "_")

)

params_str = match.group(2).strip() if match.group(2) else ""

return_type = match.group(3).strip() if match.group(3) else None

# Find method body (until next ### or ####)

method_start = match.start()

next_method = content.find("###", method_start + 1)

if next_method == -1:

method_body = content[method_start:]

else:

method_body = content[method_start:next_method]

# Extract description (text after method header, before :param)

desc_match = re.search(

r"###[^\n]+\n\n([^\n]+(?:\n(?!:param|####|###|####)[^\n]+)*)",

method_body,

re.MULTILINE,

)

description = desc_match.group(1).strip() if desc_match else ""

# Remove method name from description if it appears

description = re.sub(

r"^" + re.escape(method_name) + r"\s*$", "", description, flags=re.MULTILINE

).strip()

# Parse parameters and convert to ParamField components

param_fields = []

if params_str:

# Simple parameter parsing (split by comma, but handle type annotations)

params = []

current = ""

depth = 0

for char in params_str:

if char in "[(":

depth += 1

elif char in "])":

depth -= 1

elif char == "," and depth == 0:

if current.strip():

params.append(current.strip())

current = ""

continue

current += char

if current.strip():

params.append(current.strip())

for param in params:

# Parse: name: type = default

# Handle cases like: client: [Client](xdk.md#xdk.Client)

param_match = re.match(

r"(\w+)(?:\s*:\s*([^=]+))?(?:\s*=\s*(.+))?$", param.strip()

)

if param_match:

param_name = param_match.group(1)

param_type_raw = (

param_match.group(2).strip() if param_match.group(2) else "Any"

)

param_default = (

param_match.group(3).strip() if param_match.group(3) else None

)

# Clean type - handle markdown links first

# Pattern: [Type](path#anchor) -> extract just "Type"

link_match = re.search(r"\[([^\]]+)\]\(([^\)]+)\)", param_type_raw)

if link_match:

param_type = link_match.group(1) # Use just the link text

else:

# No link, use the raw type but clean it

param_type = param_type_raw

# Remove file references and anchors

param_type = re.sub(r"[a-z_]+\.(md|py)#[^\s]*", "", param_type)

param_type = re.sub(r"#[^\s]*", "", param_type)

# Remove incomplete link patterns like "Client]("

param_type = re.sub(r"\]\([^\)]*$", "", param_type)

param_type = re.sub(r"\]\([^\)]*\)", "", param_type)

# Clean up the type string

param_type = param_type.replace("|", " or ").strip()

# Remove any trailing/leading brackets and parentheses

param_type = re.sub(r"^[\[\(]+", "", param_type)

param_type = re.sub(r"[\]\)]+$", "", param_type)

# Remove any remaining incomplete patterns

param_type = re.sub(r"\]\(.*$", "", param_type)

# Escape angle brackets for MDX

param_type = param_type.replace("<", "&lt;").replace(">", "&gt;")

# Clean up extra spaces

param_type = re.sub(r"\s+", " ", param_type).strip()

# If type is empty or just brackets, default to Any

if not param_type or param_type in ["[", "]", "()", "(", ")", "]("]:

param_type = "Any"

# Find param description

param_desc_match = re.search(

rf":param\s+{param_name}:\s*([^\n]+)", method_body

)

param_desc = (

param_desc_match.group(1).strip() if param_desc_match else ""

)

# Build ParamField - use path instead of name

# For Python methods, parameters are function arguments

# Use "path" location for most parameters, or "body" if it's clearly a request body

param_location = (

"body"

if param_name.lower() in ["body", "data", "payload", "request"]

else "path"

)

param_field = f'<ParamField path="{param_location}.{param_name}" type="{param_type}"'

if param_default:

# Escape default value

param_default_clean = (

param_default.replace('"', "&quot;")

.replace("<", "&lt;")

.replace(">", "&gt;")

)

param_field += f' default="{param_default_clean}"'

param_field += ">"

if param_desc:

param_field += f"\n{param_desc}\n"

param_field += "</ParamField>"

param_fields.append(param_field)

# Build new method format

new_method = f"### `{method_name}`\n\n"

if description:

new_method += f"{description}\n\n"

if param_fields:

new_method += "#### Parameters\n\n"

new_method += "\n\n".join(param_fields) + "\n\n"

if return_type:

# Extract return description

return_desc_match = re.search(r":param\s+Returns?:\s*([^\n]+)", method_body)

return_desc = (

return_desc_match.group(1).strip() if return_desc_match else ""

)

# Clean return type - handle markdown links

return_type_clean = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", return_type)

return_type_clean = re.sub(

r"[a-z_]+\.(md|py)#[^\s]+", "", return_type_clean

)

return_type_clean = return_type_clean.replace("[", "").replace("]", "")

return_type_clean = return_type_clean.replace("<", "&lt;").replace(

">", "&gt;"

)

return_type_clean = re.sub(

r":param\s+\w+:\s*", "", return_type_clean

).strip()

return_type_clean = re.sub(r"\s+", " ", return_type_clean).strip()

new_method += "#### Returns\n\n"

new_method += f"`{return_type_clean}`"

if return_desc and return_desc != return_type_clean:

new_method += f" - {return_desc}"

new_method += "\n\n"

return new_method

# Convert method signatures to use ParamField components

# Match: ### method_name(params) → ReturnType

def process_all_methods(text):

# Find all method definitions

method_pattern = r"###\s+`?([^\n(]+)`?\s*\(([^)]*)\)(?:\s*→\s*([^\n]+))?"

methods = list(re.finditer(method_pattern, text, re.MULTILINE))

if not methods:

return text

# Build result by processing each method and replacing its entire section

result_parts = []

last_pos = 0

for i, match in enumerate(methods):

# Add content before this method

result_parts.append(text[last_pos : match.start()])

# Find where this method's body ends (next method or end of content)

method_start = match.start()

if i + 1 < len(methods):

next_method_start = methods[i + 1].start()

else:

next_method_start = len(text)

# Get the full method section to replace

method_section = text[method_start:next_method_start]

# Convert this method

converted = convert_method(match)

# Remove the old method content from the section

result_parts.append(converted)

last_pos = next_method_start

# Add remaining content

result_parts.append(text[last_pos:])

return "".join(result_parts)

content = process_all_methods(content)

# Clean up any remaining :param lines that weren't converted

content = re.sub(r":param\s+(\w+):\s*([^\n]+)", r"**`\1`** - \2", content)

content = re.sub(r":param\s+Returns?:\s*([^\n]+)", r"**Returns:** \1", content)

# Remove duplicate return descriptions

content = re.sub(

r"(#### Returns\n\n`[^\n]+`[^\n]+\n\n)(\*\*`[^\n]+\*\*[^\n]+\n)+",

r"\1",

content,

)

# Remove duplicate method descriptions

content = re.sub(r"(### `[^\n]+`\n\n[^\n]+\n\n[^\n]+\n\n)(\1)", r"\1", content)

# Clean up any remaining old format parameter lines after ParamField sections

content = re.sub(r"(</ParamField>\n\n)(\*\*`[^\n]+\*\*[^\n]+\n)+", r"\1", content)

# Remove duplicate "Returns:" text in return sections

content = re.sub(

r"(#### Returns\n\n`[^\n]+`)\s*-\s*\*\*`[^\n]+\*\*\s*-\s*([^\n]+)",

r"\1 - \2",

content,

)

# Remove duplicate class definitions that appear after the main class header

# Pattern: ### `class xdk.module.ClassName` followed by description and parameters

# Find the main class header (should be ## ClassName)

main_class_match = re.search(

r"##\s+([A-Z][a-zA-Z0-9_]+Client|Client|Paginator|OAuth2PKCEAuth|BaseModel)",

content,

)

if main_class_match:

# Everything after the main class header should not have duplicate class definitions

before_main = content[: main_class_match.end()]

after_main = content[main_class_match.end() :]

# Remove any class definitions from after_main

after_main = re.sub(

r"###\s+`?class\s+xdk\.[^\n]+\n\n[^\n]+\n\n(?:####\s+Parameters[^\n]+\n\n<ParamField[^>]+>\s*</ParamField>\s*\n)?",

"",

after_main,

)

content = before_main + after_main

# Remove duplicate parameter sections (#### Parameters appearing twice in a row)

content = re.sub(

r"(#### Parameters\n\n<ParamField[^>]+>\s*</ParamField>\s*\n)\1", r"\1", content

)

return content

def convert_method(match):

method_header = match.group(0)

method_name = (

match.group(1)

.strip()

.replace("*", "")

.replace("`", "")

.replace("\\", "")

.replace("_", "_")

)

params_str = match.group(2).strip() if match.group(2) else ""

return_type = match.group(3).strip() if match.group(3) else None

# Find method body (until next ### or ####)

method_start = match.start()

next_method = content.find("###", method_start + 1)

if next_method == -1:

method_body = content[method_start:]

else:

method_body = content[method_start:next_method]

# Extract description (text after method header, before :param)

desc_match = re.search(

r"###[^\n]+\n\n([^\n]+(?:\n(?!:param|####|###|####)[^\n]+)*)",

method_body,

re.MULTILINE,

)

description = desc_match.group(1).strip() if desc_match else ""

# Remove method name from description if it appears

description = re.sub(

r"^" + re.escape(method_name) + r"\s*$", "", description, flags=re.MULTILINE

).strip()

# Parse parameters and convert to ParamField components

param_fields = []

if params_str:

# Simple parameter parsing (split by comma, but handle type annotations)

params = []

current = ""

depth = 0

for char in params_str:

if char in "[(":

depth += 1

elif char in "])":

depth -= 1

elif char == "," and depth == 0:

if current.strip():

params.append(current.strip())

current = ""

continue

current += char

if current.strip():

params.append(current.strip())

for param in params:

# Parse: name: type = default

# Handle cases like: client: [Client](xdk.md#xdk.Client)

param_match = re.match(

r"(\w+)(?:\s*:\s*([^=]+))?(?:\s*=\s*(.+))?$", param.strip()

)

if param_match:

param_name = param_match.group(1)

param_type_raw = (

param_match.group(2).strip() if param_match.group(2) else "Any"

)

param_default = (

param_match.group(3).strip() if param_match.group(3) else None

)

# Clean type - handle markdown links first

# Pattern: [Type](path#anchor) -> extract just "Type"

link_match = re.search(r"\[([^\]]+)\]\(([^\)]+)\)", param_type_raw)

if link_match:

param_type = link_match.group(1) # Use just the link text

else:

# No link, use the raw type but clean it

param_type = param_type_raw

# Remove file references and anchors

param_type = re.sub(r"[a-z_]+\.(md|py)#[^\s]*", "", param_type)

param_type = re.sub(r"#[^\s]*", "", param_type)

# Remove incomplete link patterns like "Client]("

param_type = re.sub(r"\]\([^\)]*$", "", param_type)

param_type = re.sub(r"\]\([^\)]*\)", "", param_type)

# Clean up the type string

param_type = param_type.replace("|", " or ").strip()

# Remove any trailing/leading brackets and parentheses

param_type = re.sub(r"^[\[\(]+", "", param_type)

param_type = re.sub(r"[\]\)]+$", "", param_type)

# Remove any remaining incomplete patterns

param_type = re.sub(r"\]\(.*$", "", param_type)

# Escape angle brackets for MDX

param_type = param_type.replace("<", "&lt;").replace(">", "&gt;")

# Clean up extra spaces

param_type = re.sub(r"\s+", " ", param_type).strip()

# If type is empty or just brackets, default to Any

if not param_type or param_type in ["[", "]", "()", "(", ")", "]("]:

param_type = "Any"

# Find param description

param_desc_match = re.search(

rf":param\s+{param_name}:\s*([^\n]+)", method_body

)

param_desc = (

param_desc_match.group(1).strip() if param_desc_match else ""

)

# Build ParamField - use path instead of name

# For Python methods, parameters are function arguments

# Use "path" location for most parameters, or "body" if it's clearly a request body

param_location = (

"body"

if param_name.lower() in ["body", "data", "payload", "request"]

else "path"

)

param_field = f'<ParamField path="{param_location}.{param_name}" type="{param_type}"'

if param_default:

# Escape default value

param_default_clean = (

param_default.replace('"', "&quot;")

.replace("<", "&lt;")

.replace(">", "&gt;")

)

param_field += f' default="{param_default_clean}"'

param_field += ">"

if param_desc:

param_field += f"\n{param_desc}\n"

param_field += "</ParamField>"

param_fields.append(param_field)

# Build new method format

new_method = f"### `{method_name}`\n\n"

if description:

new_method += f"{description}\n\n"

if param_fields:

new_method += "#### Parameters\n\n"

new_method += "\n\n".join(param_fields) + "\n\n"

if return_type:

# Extract return description

return_desc_match = re.search(r":param\s+Returns?:\s*([^\n]+)", method_body)

return_desc = (

return_desc_match.group(1).strip() if return_desc_match else ""

)

# Clean return type - handle markdown links

return_type_clean = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", return_type)

return_type_clean = re.sub(

r"[a-z_]+\.(md|py)#[^\s]+", "", return_type_clean

)

return_type_clean = return_type_clean.replace("[", "").replace("]", "")

return_type_clean = return_type_clean.replace("<", "&lt;").replace(

">", "&gt;"

)

return_type_clean = re.sub(

r":param\s+\w+:\s*", "", return_type_clean

).strip()

return_type_clean = re.sub(r"\s+", " ", return_type_clean).strip()

new_method += "#### Returns\n\n"

new_method += f"`{return_type_clean}`"

if return_desc and return_desc != return_type_clean:

new_method += f" - {return_desc}"

new_method += "\n\n"

return new_method

# Convert method signatures to use ParamField components

# Match: ### method_name(params) → ReturnType

def process_all_methods(text):

# Find all method definitions

method_pattern = r"###\s+`?([^\n(]+)`?\s*\(([^)]*)\)(?:\s*→\s*([^\n]+))?"

methods = list(re.finditer(method_pattern, text, re.MULTILINE))

if not methods:

return text

# Build result by processing each method and replacing its entire section

result_parts = []

last_pos = 0

for i, match in enumerate(methods):

# Add content before this method

result_parts.append(text[last_pos : match.start()])

# Find where this method's body ends (next method or end of content)

method_start = match.start()

if i + 1 < len(methods):

next_method_start = methods[i + 1].start()

else:

next_method_start = len(text)

# Get the full method section to replace

method_section = text[method_start:next_method_start]

# Convert this method

converted = convert_method(match)

# Remove the old method content from the section

result_parts.append(converted)

last_pos = next_method_start

# Add remaining content

result_parts.append(text[last_pos:])

return "".join(result_parts)

content = process_all_methods(content)

# Clean up any remaining :param lines that weren't converted

content = re.sub(r":param\s+(\w+):\s*([^\n]+)", r"**`\1`** - \2", content)

content = re.sub(r":param\s+Returns?:\s*([^\n]+)", r"**Returns:** \1", content)

# Remove duplicate return descriptions

content = re.sub(

r"(#### Returns\n\n`[^\n]+`[^\n]+\n\n)(\*\*`[^\n]+\*\*[^\n]+\n)+",

r"\1",

content,

)

# Remove duplicate method descriptions

content = re.sub(r"(### `[^\n]+`\n\n[^\n]+\n\n[^\n]+\n\n)(\1)", r"\1", content)

# Clean up any remaining old format parameter lines after ParamField sections

content = re.sub(r"(</ParamField>\n\n)(\*\*`[^\n]+\*\*[^\n]+\n)+", r"\1", content)

# Remove duplicate "Returns:" text in return sections

content = re.sub(

r"(#### Returns\n\n`[^\n]+`)\s*-\s*\*\*`[^\n]+\*\*\s*-\s*([^\n]+)",

r"\1 - \2",

content,

)

# Remove duplicate class definitions that appear after the main class header

# Pattern: ### `class xdk.module.ClassName` followed by description and parameters

# Find the main class header (should be ## ClassName)

main_class_match = re.search(

r"##\s+([A-Z][a-zA-Z0-9_]+Client|Client|Paginator|OAuth2PKCEAuth|BaseModel)",

content,

)

if main_class_match:

# Everything after the main class header should not have duplicate class definitions

before_main = content[: main_class_match.end()]

after_main = content[main_class_match.end() :]

# Remove any class definitions from after_main

after_main = re.sub(

r"###\s+`?class\s+xdk\.[^\n]+\n\n[^\n]+\n\n(?:####\s+Parameters[^\n]+\n\n<ParamField[^>]+>\s*</ParamField>\s*\n)?",

"",

after_main,

)

content = before_main + after_main

# Remove duplicate parameter sections (#### Parameters appearing twice in a row)

content = re.sub(

r"(#### Parameters\n\n<ParamField[^>]+>\s*</ParamField>\s*\n)\1", r"\1", content

)

return content

def convert_method(match):

method_header = match.group(0)

method_name = (

match.group(1)

.strip()

.replace("*", "")

.replace("`", "")

.replace("\\", "")

.replace("_", "_")

)

params_str = match.group(2).strip() if match.group(2) else ""

return_type = match.group(3).strip() if match.group(3) else None

# Find method body (until next ### or ####)

method_start = match.start()

next_method = content.find("###", method_start + 1)

if next_method == -1:

method_body = content[method_start:]

else:

method_body = content[method_start:next_method]

# Extract description (text after method header, before :param)

desc_match = re.search(

r"###[^\n]+\n\n([^\n]+(?:\n(?!:param|####|###|####)[^\n]+)*)",

method_body,

re.MULTILINE,

)

description = desc_match.group(1).strip() if desc_match else ""

# Remove method name from description if it appears

description = re.sub(

r"^" + re.escape(method_name) + r"\s*$", "", description, flags=re.MULTILINE

).strip()

# Parse parameters and convert to ParamField components

param_fields = []

if params_str:

# Simple parameter parsing (split by comma, but handle type annotations)

params = []

current = ""

depth = 0

for char in params_str:

if char in "[(":

depth += 1

elif char in "])":

depth -= 1

elif char == "," and depth == 0:

if current.strip():

params.append(current.strip())

current = ""

continue

current += char

if current.strip():

params.append(current.strip())

for param in params:

# Parse: name: type = default

# Handle cases like: client: [Client](xdk.md#xdk.Client)

param_match = re.match(

r"(\w+)(?:\s*:\s*([^=]+))?(?:\s*=\s*(.+))?$", param.strip()

)