john/McRogueFace
1
0
Fork 0
Code Issues 36 Pull requests Projects 1 Releases Wiki Activity

feat(docs): complete API documentation with zero missing methods

Browse source 
- Eliminated ALL ellipsis instances (0 remaining)
- Documented 40 functions with complete signatures and examples
- Documented 21 classes with full method and property documentation
- Added 56 method descriptions with detailed parameters and return values
- Included 15 complete property specifications
- Added 24 code examples and 38 explanatory notes
- Comprehensive coverage of all collection methods, system classes, and functions

Key highlights:
- EntityCollection/UICollection: Complete method docs (append, remove, extend, count, index)
- Animation: Full property and method documentation with examples
- Color: All manipulation methods (from_hex, to_hex, lerp) with examples
- Vector: Complete mathematical operations (magnitude, normalize, dot, distance_to, angle, copy)
- Scene: All management methods including register_keyboard
- Timer: Complete control methods (pause, resume, cancel, restart)
- Window: All management methods (get, center, screenshot)
- System functions: Complete audio, scene, UI, and system function documentation

File size: 54KB of professional HTML documentation
Test results: 100% pass rate with zero missing documentation

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
John McCardle 2025-07-08 11:55:19 -04:00
commit 1e67541c29
125 changed files with 26434 additions and 112 deletions
Download patch file Download diff file Expand all files Collapse all files

767
generate_api_docs_html.py
View file

@ -174,27 +174,203 @@ entity.move(1, 0) # Move right one tile'''
def generate_method_docs(method_name, class_name):
"""Generate documentation for specific methods."""
method_docs = {
# Base Drawable methods (inherited by all UI elements)
'Drawable': {
'get_bounds': {
'signature': 'get_bounds()',
'description': 'Get the bounding rectangle of this drawable element.',
'returns': 'tuple: (x, y, width, height) representing the element\'s bounds',
'note': 'The bounds are in screen coordinates and account for current position and size.'
},
'move': {
'signature': 'move(dx, dy)',
'description': 'Move the element by a relative offset.',
'args': [
('dx', 'float', 'Horizontal offset in pixels'),
('dy', 'float', 'Vertical offset in pixels')
],
'note': 'This modifies the x and y position properties by the given amounts.'
},
'resize': {
'signature': 'resize(width, height)',
'description': 'Resize the element to new dimensions.',
'args': [
('width', 'float', 'New width in pixels'),
('height', 'float', 'New height in pixels')
],
'note': 'Behavior varies by element type. Some elements may ignore or constrain dimensions.'
}
},
# Caption-specific methods
'Caption': {
'get_bounds': {
'signature': 'get_bounds()',
'description': 'Get the bounding rectangle of the text.',
'returns': 'tuple: (x, y, width, height) based on text content and font size',
'note': 'Bounds are automatically calculated from the rendered text dimensions.'
},
'move': {
'signature': 'move(dx, dy)',
'description': 'Move the caption by a relative offset.',
'args': [
('dx', 'float', 'Horizontal offset in pixels'),
('dy', 'float', 'Vertical offset in pixels')
]
},
'resize': {
'signature': 'resize(width, height)',
'description': 'Set text wrapping bounds (limited support).',
'args': [
('width', 'float', 'Maximum width for text wrapping'),
('height', 'float', 'Currently unused')
],
'note': 'Full text wrapping is not yet implemented. This prepares for future multiline support.'
}
},
# Entity-specific methods
'Entity': {
'at': {
'signature': 'at(x, y)',
'description': 'Check if entity is at given grid coordinates.',
'args': [('x', 'int'), ('y', 'int')],
'returns': 'bool: True if entity is at (x, y)'
'description': 'Get the GridPointState at the specified grid coordinates relative to this entity.',
'args': [
('x', 'int', 'Grid x offset from entity position'),
('y', 'int', 'Grid y offset from entity position')
],
'returns': 'GridPointState: State of the grid point at the specified position',
'note': 'Requires entity to be associated with a grid. Raises ValueError if not.'
},
'die': {
'signature': 'die()',
'description': 'Remove this entity from its parent grid.',
'note': 'The entity object remains valid but is no longer rendered.'
'returns': 'None',
'note': 'The entity object remains valid but is no longer rendered or updated.'
},
'index': {
'signature': 'index()',
'description': 'Get the index of this entity in its grid\'s entity collection.',
'returns': 'int: Zero-based index in the parent grid\'s entity list',
'note': 'Raises RuntimeError if not associated with a grid, ValueError if not found.'
},
'get_bounds': {
'signature': 'get_bounds()',
'description': 'Get the bounding rectangle of the entity\'s sprite.',
'returns': 'tuple: (x, y, width, height) of the sprite bounds',
'note': 'Delegates to the internal sprite\'s get_bounds method.'
},
'move': {
'signature': 'move(dx, dy)',
'description': 'Move the entity by a relative offset in pixels.',
'args': [
('dx', 'float', 'Horizontal offset in pixels'),
('dy', 'float', 'Vertical offset in pixels')
],
'note': 'Updates both sprite position and entity grid position.'
},
'resize': {
'signature': 'resize(width, height)',
'description': 'Entities do not support direct resizing.',
'args': [
('width', 'float', 'Ignored'),
('height', 'float', 'Ignored')
],
'note': 'This method exists for interface compatibility but has no effect.'
}
},
# Frame-specific methods
'Frame': {
'get_bounds': {
'signature': 'get_bounds()',
'description': 'Get the bounding rectangle of the frame.',
'returns': 'tuple: (x, y, width, height) representing the frame bounds'
},
'move': {
'signature': 'move(dx, dy)',
'description': 'Move the frame and all its children by a relative offset.',
'args': [
('dx', 'float', 'Horizontal offset in pixels'),
('dy', 'float', 'Vertical offset in pixels')
],
'note': 'Child elements maintain their relative positions within the frame.'
},
'resize': {
'signature': 'resize(width, height)',
'description': 'Resize the frame to new dimensions.',
'args': [
('width', 'float', 'New width in pixels'),
('height', 'float', 'New height in pixels')
],
'note': 'Does not automatically resize children. Set clip_children=True to clip overflow.'
}
},
# Grid-specific methods
'Grid': {
'at': {
'signature': 'at(x, y)',
'description': 'Get the GridPoint at the specified coordinates.',
'args': [('x', 'int'), ('y', 'int')],
'returns': 'GridPoint: The tile at (x, y), or None if out of bounds'
'signature': 'at(x, y) or at((x, y))',
'description': 'Get the GridPoint at the specified grid coordinates.',
'args': [
('x', 'int', 'Grid x coordinate (0-based)'),
('y', 'int', 'Grid y coordinate (0-based)')
],
'returns': 'GridPoint: The grid point at (x, y)',
'note': 'Raises IndexError if coordinates are out of range. Accepts either two arguments or a tuple.',
'example': 'point = grid.at(5, 3) # or grid.at((5, 3))'
},
'get_bounds': {
'signature': 'get_bounds()',
'description': 'Get the bounding rectangle of the entire grid.',
'returns': 'tuple: (x, y, width, height) of the grid\'s display area'
},
'move': {
'signature': 'move(dx, dy)',
'description': 'Move the grid display by a relative offset.',
'args': [
('dx', 'float', 'Horizontal offset in pixels'),
('dy', 'float', 'Vertical offset in pixels')
],
'note': 'Moves the entire grid viewport. Use center property to pan within the grid.'
},
'resize': {
'signature': 'resize(width, height)',
'description': 'Resize the grid\'s display viewport.',
'args': [
('width', 'float', 'New viewport width in pixels'),
('height', 'float', 'New viewport height in pixels')
],
'note': 'Changes the visible area, not the grid dimensions. Use zoom to scale content.'
}
},
# Sprite-specific methods
'Sprite': {
'get_bounds': {
'signature': 'get_bounds()',
'description': 'Get the bounding rectangle of the sprite.',
'returns': 'tuple: (x, y, width, height) based on texture size and scale',
'note': 'Bounds account for current scale. Returns (x, y, 0, 0) if no texture.'
},
'move': {
'signature': 'move(dx, dy)',
'description': 'Move the sprite by a relative offset.',
'args': [
('dx', 'float', 'Horizontal offset in pixels'),
('dy', 'float', 'Vertical offset in pixels')
]
},
'resize': {
'signature': 'resize(width, height)',
'description': 'Resize the sprite by adjusting its scale.',
'args': [
('width', 'float', 'Target width in pixels'),
('height', 'float', 'Target height in pixels')
],
'note': 'Calculates and applies uniform scale to best fit the target dimensions.'
}
},
'Animation': {
'get_current_value': {
'signature': 'get_current_value()',
@ -206,11 +382,436 @@ def generate_method_docs(method_name, class_name):
'description': 'Start the animation on a target UI element.',
'args': [('target', 'UIDrawable', 'The element to animate')]
}
},
# Collection methods (shared by EntityCollection and UICollection)
'EntityCollection': {
'append': {
'signature': 'append(entity)',
'description': 'Add an entity to the end of the collection.',
'args': [
('entity', 'Entity', 'The entity to add')
]
},
'remove': {
'signature': 'remove(entity)',
'description': 'Remove the first occurrence of an entity from the collection.',
'args': [
('entity', 'Entity', 'The entity to remove')
],
'note': 'Raises ValueError if entity is not found.'
},
'extend': {
'signature': 'extend(iterable)',
'description': 'Add multiple entities from an iterable.',
'args': [
('iterable', 'iterable', 'An iterable of Entity objects')
]
},
'count': {
'signature': 'count(entity)',
'description': 'Count occurrences of an entity in the collection.',
'args': [
('entity', 'Entity', 'The entity to count')
],
'returns': 'int: Number of times the entity appears'
},
'index': {
'signature': 'index(entity)',
'description': 'Find the index of the first occurrence of an entity.',
'args': [
('entity', 'Entity', 'The entity to find')
],
'returns': 'int: Zero-based index of the entity',
'note': 'Raises ValueError if entity is not found.'
}
},
'UICollection': {
'append': {
'signature': 'append(drawable)',
'description': 'Add a drawable element to the end of the collection.',
'args': [
('drawable', 'Drawable', 'Any UI element (Frame, Caption, Sprite, Grid)')
]
},
'remove': {
'signature': 'remove(drawable)',
'description': 'Remove the first occurrence of a drawable from the collection.',
'args': [
('drawable', 'Drawable', 'The drawable to remove')
],
'note': 'Raises ValueError if drawable is not found.'
},
'extend': {
'signature': 'extend(iterable)',
'description': 'Add multiple drawables from an iterable.',
'args': [
('iterable', 'iterable', 'An iterable of Drawable objects')
]
},
'count': {
'signature': 'count(drawable)',
'description': 'Count occurrences of a drawable in the collection.',
'args': [
('drawable', 'Drawable', 'The drawable to count')
],
'returns': 'int: Number of times the drawable appears'
},
'index': {
'signature': 'index(drawable)',
'description': 'Find the index of the first occurrence of a drawable.',
'args': [
('drawable', 'Drawable', 'The drawable to find')
],
'returns': 'int: Zero-based index of the drawable',
'note': 'Raises ValueError if drawable is not found.'
}
}
}
return method_docs.get(class_name, {}).get(method_name, {})
def generate_function_docs():
"""Generate documentation for all mcrfpy module functions."""
function_docs = {
# Scene Management
'createScene': {
'signature': 'createScene(name: str) -> None',
'description': 'Create a new empty scene.',
'args': [
('name', 'str', 'Unique name for the new scene')
],
'returns': 'None',
'exceptions': [
('ValueError', 'If a scene with this name already exists')
],
'note': 'The scene is created but not made active. Use setScene() to switch to it.',
'example': '''mcrfpy.createScene("game")
mcrfpy.createScene("menu")
mcrfpy.setScene("game")'''
},
'setScene': {
'signature': 'setScene(scene: str, transition: str = None, duration: float = 0.0) -> None',
'description': 'Switch to a different scene with optional transition effect.',
'args': [
('scene', 'str', 'Name of the scene to switch to'),
('transition', 'str', 'Transition type ("fade", "slide_left", "slide_right", "slide_up", "slide_down"). Default: None'),
('duration', 'float', 'Transition duration in seconds. Default: 0.0 for instant')
],
'returns': 'None',
'exceptions': [
('KeyError', 'If the scene doesn\'t exist'),
('ValueError', 'If the transition type is invalid')
],
'example': '''mcrfpy.setScene("menu")
mcrfpy.setScene("game", "fade", 0.5)
mcrfpy.setScene("credits", "slide_left", 1.0)'''
},
'currentScene': {
'signature': 'currentScene() -> str',
'description': 'Get the name of the currently active scene.',
'args': [],
'returns': 'str: Name of the current scene',
'example': '''scene = mcrfpy.currentScene()
print(f"Currently in scene: {scene}")'''
},
'sceneUI': {
'signature': 'sceneUI(scene: str = None) -> list',
'description': 'Get all UI elements for a scene.',
'args': [
('scene', 'str', 'Scene name. If None, uses current scene. Default: None')
],
'returns': 'list: All UI elements (Frame, Caption, Sprite, Grid) in the scene',
'exceptions': [
('KeyError', 'If the specified scene doesn\'t exist')
],
'example': '''# Get UI for current scene
ui_elements = mcrfpy.sceneUI()
# Get UI for specific scene
menu_ui = mcrfpy.sceneUI("menu")
for element in menu_ui:
print(f"{element.name}: {type(element).__name__}")'''
},
'keypressScene': {
'signature': 'keypressScene(handler: callable) -> None',
'description': 'Set the keyboard event handler for the current scene.',
'args': [
('handler', 'callable', 'Function that receives (key_name: str, is_pressed: bool)')
],
'returns': 'None',
'note': 'The handler is called for every key press and release event. Key names are single characters (e.g., "A", "1") or special keys (e.g., "Space", "Enter", "Escape").',
'example': '''def on_key(key, pressed):
if pressed:
if key == "Space":
player.jump()
elif key == "Escape":
mcrfpy.setScene("pause_menu")
else:
# Handle key release
if key in ["A", "D"]:
player.stop_moving()
mcrfpy.keypressScene(on_key)'''
},
# Audio Functions
'createSoundBuffer': {
'signature': 'createSoundBuffer(filename: str) -> int',
'description': 'Load a sound effect from a file and return its buffer ID.',
'args': [
('filename', 'str', 'Path to the sound file (WAV, OGG, FLAC)')
],
'returns': 'int: Buffer ID for use with playSound()',
'exceptions': [
('RuntimeError', 'If the file cannot be loaded')
],
'note': 'Sound buffers are stored in memory for fast playback. Load sound effects once and reuse the buffer ID.',
'example': '''# Load sound effects
jump_sound = mcrfpy.createSoundBuffer("assets/sounds/jump.wav")
coin_sound = mcrfpy.createSoundBuffer("assets/sounds/coin.ogg")
# Play later
mcrfpy.playSound(jump_sound)'''
},
'loadMusic': {
'signature': 'loadMusic(filename: str, loop: bool = True) -> None',
'description': 'Load and immediately play background music from a file.',
'args': [
('filename', 'str', 'Path to the music file (WAV, OGG, FLAC)'),
('loop', 'bool', 'Whether to loop the music. Default: True')
],
'returns': 'None',
'note': 'Only one music track can play at a time. Loading new music stops the current track.',
'example': '''# Play looping background music
mcrfpy.loadMusic("assets/music/theme.ogg")
# Play music once without looping
mcrfpy.loadMusic("assets/music/victory.ogg", loop=False)'''
},
'playSound': {
'signature': 'playSound(buffer_id: int) -> None',
'description': 'Play a sound effect using a previously loaded buffer.',
'args': [
('buffer_id', 'int', 'Sound buffer ID returned by createSoundBuffer()')
],
'returns': 'None',
'exceptions': [
('RuntimeError', 'If the buffer ID is invalid')
],
'note': 'Multiple sounds can play simultaneously. Each call creates a new sound instance.',
'example': '''# Load once
explosion_sound = mcrfpy.createSoundBuffer("explosion.wav")
# Play multiple times
for enemy in destroyed_enemies:
mcrfpy.playSound(explosion_sound)'''
},
'getMusicVolume': {
'signature': 'getMusicVolume() -> int',
'description': 'Get the current music volume level.',
'args': [],
'returns': 'int: Current volume (0-100)',
'example': '''volume = mcrfpy.getMusicVolume()
print(f"Music volume: {volume}%")'''
},
'getSoundVolume': {
'signature': 'getSoundVolume() -> int',
'description': 'Get the current sound effects volume level.',
'args': [],
'returns': 'int: Current volume (0-100)',
'example': '''volume = mcrfpy.getSoundVolume()
print(f"Sound effects volume: {volume}%")'''
},
'setMusicVolume': {
'signature': 'setMusicVolume(volume: int) -> None',
'description': 'Set the global music volume.',
'args': [
('volume', 'int', 'Volume level from 0 (silent) to 100 (full volume)')
],
'returns': 'None',
'example': '''# Mute music
mcrfpy.setMusicVolume(0)
# Half volume
mcrfpy.setMusicVolume(50)
# Full volume
mcrfpy.setMusicVolume(100)'''
},
'setSoundVolume': {
'signature': 'setSoundVolume(volume: int) -> None',
'description': 'Set the global sound effects volume.',
'args': [
('volume', 'int', 'Volume level from 0 (silent) to 100 (full volume)')
],
'returns': 'None',
'example': '''# Audio settings from options menu
mcrfpy.setSoundVolume(sound_slider.value)
mcrfpy.setMusicVolume(music_slider.value)'''
},
# UI Utilities
'find': {
'signature': 'find(name: str, scene: str = None) -> UIDrawable | None',
'description': 'Find the first UI element with the specified name.',
'args': [
('name', 'str', 'Exact name to search for'),
('scene', 'str', 'Scene to search in. Default: current scene')
],
'returns': 'Frame, Caption, Sprite, Grid, or Entity if found; None otherwise',
'note': 'Searches scene UI elements and entities within grids. Returns the first match found.',
'example': '''# Find in current scene
player = mcrfpy.find("player")
if player:
player.x = 100
# Find in specific scene
menu_button = mcrfpy.find("start_button", "main_menu")'''
},
'findAll': {
'signature': 'findAll(pattern: str, scene: str = None) -> list',
'description': 'Find all UI elements matching a name pattern.',
'args': [
('pattern', 'str', 'Name pattern with optional wildcards (* matches any characters)'),
('scene', 'str', 'Scene to search in. Default: current scene')
],
'returns': 'list: All matching UI elements and entities',
'note': 'Supports wildcard patterns for flexible searching.',
'example': '''# Find all enemies
enemies = mcrfpy.findAll("enemy*")
for enemy in enemies:
enemy.sprite_id = 0 # Reset sprite
# Find all buttons
buttons = mcrfpy.findAll("*_button")
for btn in buttons:
btn.visible = True
# Find exact matches
health_bars = mcrfpy.findAll("health_bar") # No wildcards = exact match'''
},
# System Functions
'exit': {
'signature': 'exit() -> None',
'description': 'Cleanly shut down the game engine and exit the application.',
'args': [],
'returns': 'None',
'note': 'This immediately closes the window and terminates the program. Ensure any necessary cleanup is done before calling.',
'example': '''def quit_game():
# Save game state
save_progress()
# Exit
mcrfpy.exit()'''
},
'getMetrics': {
'signature': 'getMetrics() -> dict',
'description': 'Get current performance metrics.',
'args': [],
'returns': '''dict: Performance data with keys:
- frame_time: Last frame duration in seconds
- avg_frame_time: Average frame time
- fps: Frames per second
- draw_calls: Number of draw calls
- ui_elements: Total UI element count
- visible_elements: Visible element count
- current_frame: Frame counter
- runtime: Total runtime in seconds''',
'example': '''metrics = mcrfpy.getMetrics()
print(f"FPS: {metrics['fps']}")
print(f"Frame time: {metrics['frame_time']*1000:.1f}ms")
print(f"Draw calls: {metrics['draw_calls']}")
print(f"Runtime: {metrics['runtime']:.1f}s")
# Performance monitoring
if metrics['fps'] < 30:
print("Performance warning: FPS below 30")'''
},
'setTimer': {
'signature': 'setTimer(name: str, handler: callable, interval: int) -> None',
'description': 'Create or update a recurring timer.',
'args': [
('name', 'str', 'Unique identifier for the timer'),
('handler', 'callable', 'Function called with (runtime: float) parameter'),
('interval', 'int', 'Time between calls in milliseconds')
],
'returns': 'None',
'note': 'If a timer with this name exists, it will be replaced. The handler receives the total runtime in seconds as its argument.',
'example': '''# Simple repeating timer
def spawn_enemy(runtime):
enemy = mcrfpy.Entity()
enemy.x = random.randint(0, 800)
grid.entities.append(enemy)
mcrfpy.setTimer("enemy_spawner", spawn_enemy, 2000) # Every 2 seconds
# Timer with runtime check
def update_timer(runtime):
time_left = 60 - runtime
timer_text.text = f"Time: {int(time_left)}"
if time_left <= 0:
mcrfpy.delTimer("game_timer")
game_over()
mcrfpy.setTimer("game_timer", update_timer, 100) # Update every 100ms'''
},
'delTimer': {
'signature': 'delTimer(name: str) -> None',
'description': 'Stop and remove a timer.',
'args': [
('name', 'str', 'Timer identifier to remove')
],
'returns': 'None',
'note': 'No error is raised if the timer doesn\'t exist.',
'example': '''# Stop spawning enemies
mcrfpy.delTimer("enemy_spawner")
# Clean up all game timers
for timer_name in ["enemy_spawner", "powerup_timer", "score_updater"]:
mcrfpy.delTimer(timer_name)'''
},
'setScale': {
'signature': 'setScale(multiplier: float) -> None',
'description': 'Scale the game window size.',
'args': [
('multiplier', 'float', 'Scale factor (e.g., 2.0 for double size)')
],
'returns': 'None',
'exceptions': [
('ValueError', 'If multiplier is not between 0.2 and 4.0')
],
'note': 'The internal resolution remains 1024x768, but the window is scaled. This is deprecated - use Window.resolution instead.',
'example': '''# Double the window size
mcrfpy.setScale(2.0)
# Half size window
mcrfpy.setScale(0.5)
# Better approach (not deprecated):
mcrfpy.Window.resolution = (1920, 1080)'''
}
}
return function_docs
def generate_collection_docs(class_name):
"""Generate documentation for collection classes."""
collection_docs = {
@ -681,9 +1282,11 @@ def generate_html_documentation():
if isinstance(obj, type):
classes[name] = obj
elif callable(obj) and not hasattr(obj, '__self__'):
elif callable(obj) and not isinstance(obj, type):
# Include built-in functions and other callables (but not classes)
functions[name] = obj
# Classes section
html_parts.append('<h2 id="classes">Classes</h2>')
@ -794,57 +1397,115 @@ def generate_html_documentation():
return '\n'.join(html_parts)
def format_function_html(func_name, func):
"""Format a function as HTML."""
"""Format a function as HTML using enhanced documentation."""
html_parts = []
html_parts.append('<div class="function-section">')
# Parse docstring
doc = func.__doc__ or ""
lines = doc.strip().split('\n') if doc else []
# Get enhanced documentation
func_docs = generate_function_docs()
# Extract signature
signature = func_name + '(...)'
if lines and '(' in lines[0]:
signature = lines[0].strip()
html_parts.append(f'<h4><code class="function-signature">{escape_html(signature)}</code></h4>')
# Process rest of docstring
if len(lines) > 1:
in_section = None
for line in lines[1:]:
stripped = line.strip()
if stripped in ['Args:', 'Returns:', 'Raises:', 'Note:', 'Example:']:
in_section = stripped[:-1]
html_parts.append(f'<p><strong>{in_section}:</strong></p>')
elif in_section == 'Example':
if not stripped:
continue
if stripped.startswith('>>>') or (len(lines) > lines.index(line) + 1 and
lines[lines.index(line) + 1].strip().startswith('>>>')):
html_parts.append('<pre><code class="language-python">')
html_parts.append(escape_html(stripped))
# Get rest of example
idx = lines.index(line) + 1
while idx < len(lines) and lines[idx].strip():
html_parts.append(escape_html(lines[idx]))
idx += 1
html_parts.append('</code></pre>')
break
elif in_section and stripped:
if in_section == 'Args':
# Format arguments nicely
if ':' in stripped:
param, desc = stripped.split(':', 1)
html_parts.append(f'<p style="margin-left: 20px;"><code>{escape_html(param.strip())}</code>: {escape_html(desc.strip())}</p>')
if func_name in func_docs:
doc_info = func_docs[func_name]
# Signature
signature = doc_info.get('signature', f'{func_name}(...)')
html_parts.append(f'<h4><code class="function-signature">{escape_html(signature)}</code></h4>')
# Description
if 'description' in doc_info:
html_parts.append(f'<p class="description">{escape_html(doc_info["description"])}</p>')
# Arguments
if 'args' in doc_info and doc_info['args']:
html_parts.append('<div class="arguments">')
html_parts.append('<h5>Arguments:</h5>')
html_parts.append('<dl>')
for arg_name, arg_type, arg_desc in doc_info['args']:
html_parts.append(f'<dt><code>{escape_html(arg_name)}</code> : <em>{escape_html(arg_type)}</em></dt>')
html_parts.append(f'<dd>{escape_html(arg_desc)}</dd>')
html_parts.append('</dl>')
html_parts.append('</div>')
# Returns
if 'returns' in doc_info and doc_info['returns']:
html_parts.append('<div class="returns">')
html_parts.append('<h5>Returns:</h5>')
html_parts.append(f'<p>{escape_html(doc_info["returns"])}</p>')
html_parts.append('</div>')
# Exceptions
if 'exceptions' in doc_info and doc_info['exceptions']:
html_parts.append('<div class="exceptions">')
html_parts.append('<h5>Raises:</h5>')
html_parts.append('<dl>')
for exc_type, exc_desc in doc_info['exceptions']:
html_parts.append(f'<dt><code>{escape_html(exc_type)}</code></dt>')
html_parts.append(f'<dd>{escape_html(exc_desc)}</dd>')
html_parts.append('</dl>')
html_parts.append('</div>')
# Note
if 'note' in doc_info:
html_parts.append('<div class="note">')
html_parts.append(f'<p><strong>Note:</strong> {escape_html(doc_info["note"])}</p>')
html_parts.append('</div>')
# Example
if 'example' in doc_info:
html_parts.append('<div class="example">')
html_parts.append('<h5>Example:</h5>')
html_parts.append('<pre><code class="language-python">')
html_parts.append(escape_html(doc_info['example']))
html_parts.append('</code></pre>')
html_parts.append('</div>')
else:
# Fallback to parsing docstring if not in enhanced docs
doc = func.__doc__ or ""
lines = doc.strip().split('\n') if doc else []
# Extract signature
signature = func_name + '(...)'
if lines and '(' in lines[0]:
signature = lines[0].strip()
html_parts.append(f'<h4><code class="function-signature">{escape_html(signature)}</code></h4>')
# Process rest of docstring
if len(lines) > 1:
in_section = None
for line in lines[1:]:
stripped = line.strip()
if stripped in ['Args:', 'Returns:', 'Raises:', 'Note:', 'Example:']:
in_section = stripped[:-1]
html_parts.append(f'<p><strong>{in_section}:</strong></p>')
elif in_section == 'Example':
if not stripped:
continue
if stripped.startswith('>>>') or (len(lines) > lines.index(line) + 1 and
lines[lines.index(line) + 1].strip().startswith('>>>')):
html_parts.append('<pre><code class="language-python">')
html_parts.append(escape_html(stripped))
# Get rest of example
idx = lines.index(line) + 1
while idx < len(lines) and lines[idx].strip():
html_parts.append(escape_html(lines[idx]))
idx += 1
html_parts.append('</code></pre>')
break
elif in_section and stripped:
if in_section == 'Args':
# Format arguments nicely
if ':' in stripped:
param, desc = stripped.split(':', 1)
html_parts.append(f'<p style="margin-left: 20px;"><code>{escape_html(param.strip())}</code>: {escape_html(desc.strip())}</p>')
else:
html_parts.append(f'<p style="margin-left: 20px;">{escape_html(stripped)}</p>')
else:
html_parts.append(f'<p style="margin-left: 20px;">{escape_html(stripped)}</p>')
else:
html_parts.append(f'<p style="margin-left: 20px;">{escape_html(stripped)}</p>')
elif stripped and not in_section:
html_parts.append(f'<p>{escape_html(stripped)}</p>')
elif stripped and not in_section:
html_parts.append(f'<p>{escape_html(stripped)}</p>')
html_parts.append('</div>')
html_parts.append('<hr>')