Add Python stub generation.

[andrewleech]

Summary

This PR implements comprehensive Python stub file (.pyi) generation for LVGL MicroPython bindings, providing full IDE support with autocompletion, type hints, and rich documentation extracted from LVGL C headers.

Key Features

• 🚀 Fast Parallel Processing: 6 seconds vs. minutes (uses all CPU cores)
• 📝 Rich Documentation: Automatic extraction from 1400+ LVGL functions
• 🎯 IDE Integration: Full autocompletion and type hints (.pyi files)
• 🔗 Source Navigation: File:line references to original C implementation
• ⚡ Separate Build: Doesn't slow down main MicroPython builds
• 🔧 Smart Formatting: Bullet points, text wrapping, proper Python conventions

Performance Improvements

Before:

• Stub generation was part of main build, slowing it down significantly
• Serial processing of 200+ files taking minutes
• Each function required searching through all files repeatedly

After:

• ⚡ 6 seconds vs. minutes for documentation parsing
• 🔄 Parallel processing using all CPU cores (4 processes for 209 files)
• 📊 Pre-indexed documentation for O(1) function lookups vs O(n) searches
• 🎯 Separate build target - main build stays fast

Generated Content Examples

Class Methods with Self Parameter and Source References:

class label:
    def set_text(self: Self, text: str) -> None:
        """
        Set a new text for a label. Memory will be allocated to store the text by the label.
        
        Args:
            text (str): '\0' terminated character string. NULL to refresh with the current text.
        
        Source: src/widgets/label/lv_label.h:88
        """
        ...
    
    def get_scroll_x(self: Self) -> int:
        """
        Get current X scroll position. Identical to `lv_obj_get_scroll_left()`.
        
        Returns:
            current scroll position from left edge
            - If Widget is not scrolled return 0.
            - If scrolled return > 0.
            - If scrolled inside (elastic scroll) return < 0.
        
        Source: src/core/lv_obj_scroll.h:122
        """
        ...

Module Functions:

def task_handler() -> int:
    """
    Call it periodically to handle lv_timers and refresh the display.
    
    Returns:
        time till next timer should run
    
    Source: src/core/lv_timer.h:77
    """
    ...

Technical Implementation

1. Parallel Processing Architecture:

   • ProcessPoolExecutor distributes file processing across CPU cores
   • Progress reporting every 50 processed files
   • Graceful fallback to serial processing if parallel fails
   • Pre-indexing builds function documentation index once for O(1) lookups

2. Doxygen Comment Parsing:

   • Custom regex-based parsing using Python built-ins (no external dependencies)
   • Supports @param, @return tags with proper formatting
   • Handles multi-line descriptions with bullet points
   • Preserves line structure for proper formatting

3. Python Stub Generation:

   • Converts C types to Python type hints (lv_obj_t* → obj)
   • Renames first parameter from 'obj' to 'self' in class methods
   • Generates proper docstrings with Args and Returns sections
   • Text wrapping at ~85 characters for readability
   • Source file:line references for navigation to C code

Build System Changes

Main Build (Fast):

make USER_C_MODULES=../../lib/lvgl  # No documentation parsing

Stub Generation (Separate):

cd lib/lvgl
python3 gen/gen_mpy.py -M lvgl -MP lv -S output_dir -E preprocessed.pp lvgl/lvgl.h

Results

• Processing: 209 header files → 1423 documented functions
• Time: ~6 seconds with parallel processing
• CPU Utilization: Uses all available cores efficiently
• Memory: Pre-indexed for fast lookups
• Build Impact: Zero - main build unaffected
• Source Navigation: Every function includes file:line reference

Testing

• ✅ Tested on Linux with 4 CPU cores
• ✅ Verified parallel processing performance improvements
• ✅ Confirmed bullet point formatting works correctly
• ✅ Validated self parameter renaming for class methods
• ✅ Checked type hint generation for all supported types
• ✅ Ensured build system separation works properly
• ✅ Verified source file references are accurate

Trade-offs and Alternatives

Trade-offs:

• Additional complexity in build system (separate target)
• Requires multiprocessing support (graceful fallback included)
• Uses more CPU during stub generation (but much faster overall)

Alternatives Considered:

• External documentation tools (rejected for complexity/dependencies)
• Serial processing only (rejected for performance)
• Including stubs in main build (rejected for build speed impact)

Why This Approach:

• No external dependencies - uses only Python standard library
• Significant performance improvement with parallel processing
• Clean separation of concerns - main build stays fast
• Comprehensive IDE support matching modern Python libraries
• Source navigation enables efficient debugging and contribution

Documentation

Added comprehensive documentation in DOCSTRING_PARSING.md covering:

• Complete technical implementation details
• Usage examples and IDE benefits
• Performance characteristics and architecture
• Development impact and benefits
• Source reference functionality

🤖 Generated with Claude Code

[andrewleech]

Closing this PR as it was created on master branch. Recreated as #388 from proper feature branch.