#!/usr/bin/env python3
"""Generate high-quality HTML API reference documentation for McRogueFace."""

import os
import sys
import datetime
import html
from pathlib import Path
import mcrfpy

def escape_html(text: str) -> str:
    """Escape HTML special characters."""
    return html.escape(text) if text else ""

def format_docstring_as_html(docstring: str) -> str:
    """Convert docstring to properly formatted HTML."""
    if not docstring:
        return ""
    
    # Split and process lines
    lines = docstring.strip().split('\n')
    result = []
    in_code_block = False
    
    for line in lines:
        # Convert \n to actual newlines
        line = line.replace('\\n', '\n')
        
        # Handle code blocks
        if line.strip().startswith('```'):
            if in_code_block:
                result.append('</pre></code>')
                in_code_block = False
            else:
                result.append('<code><pre>')
                in_code_block = True
            continue
            
        # Convert markdown-style code to HTML
        if '`' in line and not in_code_block:
            import re
            line = re.sub(r'`([^`]+)`', r'<code>\1</code>', line)
        
        if in_code_block:
            result.append(escape_html(line))
        else:
            result.append(escape_html(line) + '<br>')
    
    if in_code_block:
        result.append('</pre></code>')
    
    return '\n'.join(result)

def get_class_details(cls):
    """Get detailed information about a class."""
    info = {
        'name': cls.__name__,
        'doc': cls.__doc__ or "",
        'methods': {},
        'properties': {},
        'bases': []
    }
    
    # Get real base classes (excluding object)
    for base in cls.__bases__:
        if base.__name__ != 'object':
            info['bases'].append(base.__name__)
    
    # Special handling for Entity which doesn't inherit from Drawable
    if cls.__name__ == 'Entity' and 'Drawable' in info['bases']:
        info['bases'].remove('Drawable')
    
    # Get methods and properties
    for attr_name in dir(cls):
        if attr_name.startswith('__') and attr_name != '__init__':
            continue
            
        try:
            attr = getattr(cls, attr_name)
            
            if isinstance(attr, property):
                info['properties'][attr_name] = {
                    'doc': (attr.fget.__doc__ if attr.fget else "") or "",
                    'readonly': attr.fset is None
                }
            elif callable(attr) and not attr_name.startswith('_'):
                info['methods'][attr_name] = attr.__doc__ or ""
        except:
            pass
    
    return info

def generate_class_init_docs(class_name):
    """Generate initialization documentation for specific classes."""
    init_docs = {
        'Entity': {
            'signature': 'Entity(x=0, y=0, sprite_id=0)',
            'description': 'Game entity that can be placed in a Grid.',
            'args': [
                ('x', 'int', 'Grid x coordinate. Default: 0'),
                ('y', 'int', 'Grid y coordinate. Default: 0'),
                ('sprite_id', 'int', 'Sprite index for rendering. Default: 0')
            ],
            'example': '''entity = mcrfpy.Entity(5, 10, 42)
entity.move(1, 0)  # Move right one tile'''
        },
        'Color': {
            'signature': 'Color(r=255, g=255, b=255, a=255)',
            'description': 'RGBA color representation.',
            'args': [
                ('r', 'int', 'Red component (0-255). Default: 255'),
                ('g', 'int', 'Green component (0-255). Default: 255'),
                ('b', 'int', 'Blue component (0-255). Default: 255'),
                ('a', 'int', 'Alpha component (0-255). Default: 255')
            ],
            'example': 'red = mcrfpy.Color(255, 0, 0)'
        },
        'Font': {
            'signature': 'Font(filename)',
            'description': 'Load a font from file.',
            'args': [
                ('filename', 'str', 'Path to font file (TTF/OTF)')
            ]
        },
        'Texture': {
            'signature': 'Texture(filename)',
            'description': 'Load a texture from file.',
            'args': [
                ('filename', 'str', 'Path to image file (PNG/JPG/BMP)')
            ]
        },
        'Vector': {
            'signature': 'Vector(x=0.0, y=0.0)',
            'description': '2D vector for positions and directions.',
            'args': [
                ('x', 'float', 'X component. Default: 0.0'),
                ('y', 'float', 'Y component. Default: 0.0')
            ]
        },
        'Animation': {
            'signature': 'Animation(property_name, start_value, end_value, duration, transition="linear", loop=False)',
            'description': 'Animate UI element properties over time.',
            'args': [
                ('property_name', 'str', 'Property to animate (e.g., "x", "y", "scale")'),
                ('start_value', 'float', 'Starting value'),
                ('end_value', 'float', 'Ending value'),
                ('duration', 'float', 'Duration in seconds'),
                ('transition', 'str', 'Easing function. Default: "linear"'),
                ('loop', 'bool', 'Whether to loop. Default: False')
            ],
            'properties': ['current_value', 'elapsed_time', 'is_running', 'is_finished']
        },
        'GridPoint': {
            'description': 'Represents a single tile in a Grid.',
            'properties': ['x', 'y', 'texture_index', 'solid', 'transparent', 'color']
        },
        'GridPointState': {
            'description': 'State information for a GridPoint.',
            'properties': ['visible', 'discovered', 'custom_flags']
        },
        'Timer': {
            'signature': 'Timer(name, callback, interval_ms)',
            'description': 'Create a recurring timer.',
            'args': [
                ('name', 'str', 'Unique timer identifier'),
                ('callback', 'callable', 'Function to call'),
                ('interval_ms', 'int', 'Interval in milliseconds')
            ]
        }
    }
    
    return init_docs.get(class_name, {})

def generate_method_docs(method_name, class_name):
    """Generate documentation for specific methods."""
    method_docs = {
        '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)'
            },
            'die': {
                'signature': 'die()',
                'description': 'Remove this entity from its parent grid.',
                'note': 'The entity object remains valid but is no longer rendered.'
            }
        },
        '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'
            }
        },
        'Animation': {
            'get_current_value': {
                'signature': 'get_current_value()',
                'description': 'Get the current interpolated value.',
                'returns': 'float: Current animation value'
            },
            'start': {
                'signature': 'start(target)',
                'description': 'Start the animation on a target UI element.',
                'args': [('target', 'UIDrawable', 'The element to animate')]
            }
        }
    }
    
    return method_docs.get(class_name, {}).get(method_name, {})

def generate_collection_docs(class_name):
    """Generate documentation for collection classes."""
    collection_docs = {
        'EntityCollection': {
            'description': 'Container for Entity objects in a Grid. Supports iteration and indexing.',
            'methods': {
                'append': 'Add an entity to the collection',
                'remove': 'Remove an entity from the collection',
                'extend': 'Add multiple entities from an iterable',
                'count': 'Count occurrences of an entity',
                'index': 'Find the index of an entity'
            }
        },
        'UICollection': {
            'description': 'Container for UI drawable elements. Supports iteration and indexing.',
            'methods': {
                'append': 'Add a UI element to the collection',
                'remove': 'Remove a UI element from the collection',
                'extend': 'Add multiple UI elements from an iterable',
                'count': 'Count occurrences of a UI element',
                'index': 'Find the index of a UI element'
            }
        },
        'UICollectionIter': {
            'description': 'Iterator for UICollection. Automatically created when iterating over a UICollection.'
        },
        'UIEntityCollectionIter': {
            'description': 'Iterator for EntityCollection. Automatically created when iterating over an EntityCollection.'
        }
    }
    
    return collection_docs.get(class_name, {})

def format_class_html(cls_info, class_name):
    """Format a class as HTML with proper structure."""
    html_parts = []
    
    # Class header
    html_parts.append(f'<div class="class-section" id="class-{class_name}">')
    html_parts.append(f'<h3>class <span class="class-name">{class_name}</span></h3>')
    
    # Inheritance
    if cls_info['bases']:
        html_parts.append(f'<p class="inheritance"><em>Inherits from: {", ".join(cls_info["bases"])}</em></p>')
    
    # Get additional documentation
    init_info = generate_class_init_docs(class_name)
    collection_info = generate_collection_docs(class_name)
    
    # Constructor signature for classes with __init__
    if init_info.get('signature'):
        html_parts.append('<div class="constructor">')
        html_parts.append('<pre><code class="language-python">')
        html_parts.append(escape_html(init_info['signature']))
        html_parts.append('</code></pre>')
        html_parts.append('</div>')
    
    # Description
    description = ""
    if collection_info.get('description'):
        description = collection_info['description']
    elif init_info.get('description'):
        description = init_info['description']
    elif cls_info['doc']:
        # Parse description from docstring
        doc_lines = cls_info['doc'].strip().split('\n')
        # Skip constructor line if present
        start_idx = 1 if doc_lines and '(' in doc_lines[0] else 0
        if start_idx < len(doc_lines):
            description = '\n'.join(doc_lines[start_idx:]).strip()
    
    if description:
        html_parts.append('<div class="description">')
        html_parts.append(f'<p>{format_docstring_as_html(description)}</p>')
        html_parts.append('</div>')
    
    # Constructor arguments
    if init_info.get('args'):
        html_parts.append('<div class="arguments">')
        html_parts.append('<h4>Arguments:</h4>')
        html_parts.append('<dl>')
        for arg_name, arg_type, arg_desc in init_info['args']:
            html_parts.append(f'<dt><code>{arg_name}</code> (<em>{arg_type}</em>)</dt>')
            html_parts.append(f'<dd>{escape_html(arg_desc)}</dd>')
        html_parts.append('</dl>')
        html_parts.append('</div>')
    
    # Properties/Attributes
    props = cls_info.get('properties', {})
    if props or init_info.get('properties'):
        html_parts.append('<div class="properties">')
        html_parts.append('<h4>Attributes:</h4>')
        html_parts.append('<dl>')
        
        # Add documented properties from init_info
        if init_info.get('properties'):
            for prop_name in init_info['properties']:
                html_parts.append(f'<dt><code class="property">{prop_name}</code></dt>')
                html_parts.append(f'<dd>Property of {class_name}</dd>')
        
        # Add actual properties
        for prop_name, prop_info in props.items():
            readonly = ' <em>(read-only)</em>' if prop_info.get('readonly') else ''
            html_parts.append(f'<dt><code class="property">{prop_name}</code>{readonly}</dt>')
            if prop_info.get('doc'):
                html_parts.append(f'<dd>{escape_html(prop_info["doc"])}</dd>')
        
        html_parts.append('</dl>')
        html_parts.append('</div>')
    
    # Methods
    methods = cls_info.get('methods', {})
    collection_methods = collection_info.get('methods', {})
    
    if methods or collection_methods:
        html_parts.append('<div class="methods">')
        html_parts.append('<h4>Methods:</h4>')
        
        for method_name, method_doc in {**collection_methods, **methods}.items():
            if method_name == '__init__':
                continue
                
            html_parts.append('<div class="method">')
            
            # Get specific method documentation
            method_info = generate_method_docs(method_name, class_name)
            
            if method_info:
                # Use detailed documentation
                html_parts.append(f'<h5><code class="method">{method_info["signature"]}</code></h5>')
                html_parts.append(f'<p>{escape_html(method_info["description"])}</p>')
                
                if method_info.get('args'):
                    html_parts.append('<p><strong>Arguments:</strong></p>')
                    html_parts.append('<ul>')
                    for arg in method_info['args']:
                        if len(arg) == 3:
                            html_parts.append(f'<li><code>{arg[0]}</code> ({arg[1]}): {arg[2]}</li>')
                        else:
                            html_parts.append(f'<li><code>{arg[0]}</code> ({arg[1]})</li>')
                    html_parts.append('</ul>')
                
                if method_info.get('returns'):
                    html_parts.append(f'<p><strong>Returns:</strong> {escape_html(method_info["returns"])}</p>')
                
                if method_info.get('note'):
                    html_parts.append(f'<p><strong>Note:</strong> {escape_html(method_info["note"])}</p>')
            else:
                # Use docstring
                html_parts.append(f'<h5><code class="method">{method_name}(...)</code></h5>')
                if isinstance(method_doc, str) and method_doc:
                    html_parts.append(f'<p>{escape_html(method_doc)}</p>')
            
            html_parts.append('</div>')
        
        html_parts.append('</div>')
    
    # Example
    if init_info.get('example'):
        html_parts.append('<div class="example">')
        html_parts.append('<h4>Example:</h4>')
        html_parts.append('<pre><code class="language-python">')
        html_parts.append(escape_html(init_info['example']))
        html_parts.append('</code></pre>')
        html_parts.append('</div>')
    
    html_parts.append('</div>')
    html_parts.append('<hr>')
    
    return '\n'.join(html_parts)

def generate_html_documentation():
    """Generate complete HTML API documentation."""
    html_parts = []
    
    # HTML header
    html_parts.append('''<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>McRogueFace API Reference</title>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
            line-height: 1.6;
            color: #333;
            max-width: 1200px;
            margin: 0 auto;
            padding: 20px;
            background: #f8f9fa;
        }
        
        .container {
            background: white;
            padding: 30px;
            border-radius: 8px;
            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
        }
        
        h1 { 
            color: #2c3e50; 
            border-bottom: 3px solid #3498db; 
            padding-bottom: 15px;
            margin-bottom: 30px;
        }
        
        h2 { 
            color: #34495e; 
            border-bottom: 2px solid #ecf0f1; 
            padding-bottom: 10px;
            margin-top: 40px;
        }
        
        h3 { 
            color: #2c3e50; 
            margin-top: 30px;
        }
        
        h4 {
            color: #34495e;
            margin-top: 20px;
            font-size: 1.1em;
        }
        
        h5 {
            color: #555;
            margin-top: 15px;
            font-size: 1em;
        }
        
        code {
            background: #f4f4f4;
            padding: 2px 6px;
            border-radius: 3px;
            font-family: "SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Consolas, monospace;
            font-size: 0.9em;
        }
        
        pre {
            background: #f8f8f8;
            border: 1px solid #e1e4e8;
            border-radius: 6px;
            padding: 16px;
            overflow-x: auto;
            margin: 15px 0;
        }
        
        pre code {
            background: none;
            padding: 0;
            font-size: 0.875em;
            line-height: 1.45;
        }
        
        .class-name {
            color: #8e44ad;
            font-weight: bold;
        }
        
        .property {
            color: #27ae60;
            font-weight: 600;
        }
        
        .method {
            color: #2980b9;
            font-weight: 600;
        }
        
        .inheritance {
            color: #7f8c8d;
            font-size: 0.9em;
            margin-top: -10px;
        }
        
        .toc {
            background: #f8f9fa;
            border: 1px solid #e1e4e8;
            border-radius: 6px;
            padding: 20px;
            margin: 20px 0;
        }
        
        .toc h2 {
            margin-top: 0;
            border: none;
            padding: 0;
        }
        
        .toc ul {
            list-style: none;
            padding-left: 0;
        }
        
        .toc li {
            margin: 8px 0;
        }
        
        .toc a {
            color: #3498db;
            text-decoration: none;
            font-weight: 500;
        }
        
        .toc a:hover {
            text-decoration: underline;
        }
        
        .class-section, .function-section {
            margin: 30px 0;
            padding: 20px;
            background: #fafbfc;
            border-radius: 6px;
            border: 1px solid #e1e4e8;
        }
        
        .description {
            margin: 15px 0;
            color: #4a5568;
        }
        
        .arguments, .properties, .methods {
            margin: 20px 0;
        }
        
        dl {
            margin: 10px 0;
        }
        
        dt {
            font-weight: 600;
            margin-top: 10px;
            color: #2c3e50;
        }
        
        dd {
            margin-left: 20px;
            margin-bottom: 10px;
            color: #555;
        }
        
        .example {
            margin: 20px 0;
            padding: 15px;
            background: #f0f7ff;
            border-left: 4px solid #3498db;
            border-radius: 4px;
        }
        
        .example h4 {
            margin-top: 0;
            color: #2980b9;
        }
        
        hr {
            border: none;
            border-top: 1px solid #e1e4e8;
            margin: 30px 0;
        }
        
        .timestamp {
            color: #7f8c8d;
            font-style: italic;
            font-size: 0.9em;
        }
        
        .overview {
            background: #e8f4fd;
            border-left: 4px solid #3498db;
            padding: 20px;
            margin: 20px 0;
            border-radius: 4px;
        }
        
        .overview pre {
            background: white;
            border: 1px solid #d6e9f5;
        }
        
        strong {
            color: #2c3e50;
        }
        
        em {
            color: #555;
        }
        
        .automation-section {
            background: #f0f9ff;
            border: 1px solid #b8daff;
            border-radius: 6px;
            padding: 20px;
            margin-top: 30px;
        }
        
        .automation-section h2 {
            color: #004085;
            border-bottom: 2px solid #b8daff;
        }
        
        .function-signature {
            font-family: "SF Mono", Monaco, monospace;
            font-size: 1.1em;
            color: #d73a49;
        }
    </style>
</head>
<body>
    <div class="container">
''')
    
    # Title and timestamp
    html_parts.append('<h1>McRogueFace API Reference</h1>')
    html_parts.append(f'<p class="timestamp">Generated on {datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")}</p>')
    
    # Overview
    if mcrfpy.__doc__:
        html_parts.append('<div class="overview">')
        html_parts.append('<h2>Overview</h2>')
        # Process the docstring properly
        doc_lines = mcrfpy.__doc__.strip().split('\\n')
        for line in doc_lines:
            if line.strip().startswith('Example:'):
                html_parts.append('<h4>Example:</h4>')
                html_parts.append('<pre><code class="language-python">')
            elif line.strip() and not line.startswith(' '):
                html_parts.append(f'<p>{escape_html(line)}</p>')
            elif line.strip():
                # Code line
                html_parts.append(escape_html(line))
        html_parts.append('</code></pre>')
        html_parts.append('</div>')
    
    # Table of Contents
    html_parts.append('<div class="toc">')
    html_parts.append('<h2>Table of Contents</h2>')
    html_parts.append('<ul>')
    html_parts.append('<li><a href="#classes">Classes</a>')
    html_parts.append('<ul>')
    html_parts.append('<li><a href="#ui-components">UI Components</a></li>')
    html_parts.append('<li><a href="#collections">Collections</a></li>')
    html_parts.append('<li><a href="#system-types">System Types</a></li>')
    html_parts.append('<li><a href="#other-classes">Other Classes</a></li>')
    html_parts.append('</ul>')
    html_parts.append('</li>')
    html_parts.append('<li><a href="#functions">Functions</a>')
    html_parts.append('<ul>')
    html_parts.append('<li><a href="#scene-management">Scene Management</a></li>')
    html_parts.append('<li><a href="#audio">Audio</a></li>')
    html_parts.append('<li><a href="#ui-utilities">UI Utilities</a></li>')
    html_parts.append('<li><a href="#system">System</a></li>')
    html_parts.append('</ul>')
    html_parts.append('</li>')
    html_parts.append('<li><a href="#automation">Automation Module</a></li>')
    html_parts.append('</ul>')
    html_parts.append('</div>')
    
    # Collect all components
    classes = {}
    functions = {}
    
    for name in sorted(dir(mcrfpy)):
        if name.startswith('_'):
            continue
        
        obj = getattr(mcrfpy, name)
        
        if isinstance(obj, type):
            classes[name] = obj
        elif callable(obj) and not hasattr(obj, '__self__'):
            functions[name] = obj
    
    # Classes section
    html_parts.append('<h2 id="classes">Classes</h2>')
    
    # Group classes
    ui_classes = ['Frame', 'Caption', 'Sprite', 'Grid', 'Entity']
    collection_classes = ['EntityCollection', 'UICollection', 'UICollectionIter', 'UIEntityCollectionIter']
    system_classes = ['Color', 'Vector', 'Texture', 'Font']
    other_classes = [name for name in classes if name not in ui_classes + collection_classes + system_classes]
    
    # UI Components
    html_parts.append('<h3 id="ui-components">UI Components</h3>')
    for class_name in ui_classes:
        if class_name in classes:
            cls_info = get_class_details(classes[class_name])
            html_parts.append(format_class_html(cls_info, class_name))
    
    # Collections
    html_parts.append('<h3 id="collections">Collections</h3>')
    for class_name in collection_classes:
        if class_name in classes:
            cls_info = get_class_details(classes[class_name])
            html_parts.append(format_class_html(cls_info, class_name))
    
    # System Types
    html_parts.append('<h3 id="system-types">System Types</h3>')
    for class_name in system_classes:
        if class_name in classes:
            cls_info = get_class_details(classes[class_name])
            html_parts.append(format_class_html(cls_info, class_name))
    
    # Other Classes
    html_parts.append('<h3 id="other-classes">Other Classes</h3>')
    for class_name in other_classes:
        if class_name in classes:
            cls_info = get_class_details(classes[class_name])
            html_parts.append(format_class_html(cls_info, class_name))
    
    # Functions section
    html_parts.append('<h2 id="functions">Functions</h2>')
    
    # Group functions by category
    scene_funcs = ['createScene', 'setScene', 'currentScene', 'sceneUI', 'keypressScene']
    audio_funcs = ['createSoundBuffer', 'loadMusic', 'playSound', 'getMusicVolume', 
                   'getSoundVolume', 'setMusicVolume', 'setSoundVolume']
    ui_funcs = ['find', 'findAll']
    system_funcs = ['exit', 'getMetrics', 'setTimer', 'delTimer', 'setScale']
    
    # Scene Management
    html_parts.append('<h3 id="scene-management">Scene Management</h3>')
    for func_name in scene_funcs:
        if func_name in functions:
            html_parts.append(format_function_html(func_name, functions[func_name]))
    
    # Audio
    html_parts.append('<h3 id="audio">Audio</h3>')
    for func_name in audio_funcs:
        if func_name in functions:
            html_parts.append(format_function_html(func_name, functions[func_name]))
    
    # UI Utilities
    html_parts.append('<h3 id="ui-utilities">UI Utilities</h3>')
    for func_name in ui_funcs:
        if func_name in functions:
            html_parts.append(format_function_html(func_name, functions[func_name]))
    
    # System
    html_parts.append('<h3 id="system">System</h3>')
    for func_name in system_funcs:
        if func_name in functions:
            html_parts.append(format_function_html(func_name, functions[func_name]))
    
    # Automation Module
    if hasattr(mcrfpy, 'automation'):
        html_parts.append('<div class="automation-section">')
        html_parts.append('<h2 id="automation">Automation Module</h2>')
        html_parts.append('<p>The <code>mcrfpy.automation</code> module provides testing and automation capabilities for simulating user input and capturing screenshots.</p>')
        
        automation = mcrfpy.automation
        auto_funcs = []
        
        for name in sorted(dir(automation)):
            if not name.startswith('_'):
                obj = getattr(automation, name)
                if callable(obj):
                    auto_funcs.append((name, obj))
        
        for name, func in auto_funcs:
            html_parts.append('<div class="function-section">')
            html_parts.append(f'<h4><code class="function-signature">automation.{name}</code></h4>')
            if func.__doc__:
                # Extract just the description, not the repeated signature
                doc_lines = func.__doc__.strip().split(' - ')
                if len(doc_lines) > 1:
                    description = doc_lines[1]
                else:
                    description = func.__doc__.strip()
                html_parts.append(f'<p>{escape_html(description)}</p>')
            html_parts.append('</div>')
        
        html_parts.append('</div>')
    
    # Close HTML
    html_parts.append('''
    </div>
</body>
</html>''')
    
    return '\n'.join(html_parts)

def format_function_html(func_name, func):
    """Format a function as HTML."""
    html_parts = []
    
    html_parts.append('<div class="function-section">')
    
    # Parse docstring
    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>')
            elif stripped and not in_section:
                html_parts.append(f'<p>{escape_html(stripped)}</p>')
    
    html_parts.append('</div>')
    html_parts.append('<hr>')
    
    return '\n'.join(html_parts)

def main():
    """Generate improved HTML API documentation."""
    print("Generating improved HTML API documentation...")
    
    # Generate HTML
    html_content = generate_html_documentation()
    
    # Write to file
    output_path = Path("docs/api_reference_improved.html")
    output_path.parent.mkdir(exist_ok=True)
    
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(html_content)
    
    print(f"✓ Generated {output_path}")
    print(f"  File size: {len(html_content):,} bytes")
    
    # Also generate a test to verify the HTML
    test_content = '''#!/usr/bin/env python3
"""Test the improved HTML API documentation."""

import os
import sys
from pathlib import Path

def test_html_quality():
    """Test that the HTML documentation meets quality standards."""
    html_path = Path("docs/api_reference_improved.html")
    
    if not html_path.exists():
        print("ERROR: HTML documentation not found")
        return False
        
    with open(html_path, 'r') as f:
        content = f.read()
    
    # Check for common issues
    issues = []
    
    # Check that \\n is not present literally
    if '\\\\n' in content:
        issues.append("Found literal \\\\n in HTML content")
    
    # Check that markdown links are converted
    if '[' in content and '](#' in content:
        issues.append("Found unconverted markdown links")
    
    # Check for proper HTML structure
    if '<h4>Args:</h4>' in content:
        issues.append("Args: should not be an H4 heading")
    
    if '<h4>Attributes:</h4>' not in content:
        issues.append("Missing proper Attributes: headings")
    
    # Check for duplicate method descriptions
    if content.count('Get bounding box as (x, y, width, height)') > 20:
        issues.append("Too many duplicate method descriptions")
    
    # Check specific improvements
    if 'Entity' in content and 'Inherits from: Drawable' in content:
        issues.append("Entity incorrectly shown as inheriting from Drawable")
    
    if not issues:
        print("✓ HTML documentation passes all quality checks")
        return True
    else:
        print("Issues found:")
        for issue in issues:
            print(f"  - {issue}")
        return False

if __name__ == '__main__':
    if test_html_quality():
        print("PASS")
        sys.exit(0)
    else:
        print("FAIL")
        sys.exit(1)
'''
    
    test_path = Path("tests/test_html_quality.py")
    with open(test_path, 'w') as f:
        f.write(test_content)
    
    print(f"✓ Generated test at {test_path}")

if __name__ == '__main__':
    main()