lv_binding_micropython icon indicating copy to clipboard operation
lv_binding_micropython copied to clipboard

Add Python stub file generation with documentation parsing

Open andrewleech opened this issue 6 months ago • 1 comments

Summary

This PR adds comprehensive Python stub file (.pyi) generation for the LVGL MicroPython bindings, providing full IDE support with autocompletion, type hints, and rich documentation.

Key Features:

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

The implementation includes:

  1. Stub Generation: Creates .pyi files with proper Python type hints
  2. Documentation Parsing: Extracts Doxygen comments from C headers using parallel processing
  3. Smart Parameter Handling: Converts obj to self for class methods
  4. Performance Optimization: Processes 209 header files in ~6 seconds using all CPU cores
  5. Source References: Adds file:line references for navigation to C implementation

Testing

Tested on Unix port with full stub generation:

  • Processes 209 LVGL header files using parallel processing
  • Extracts documentation from 1423 functions
  • Generates type hints for 41 widget classes and 64 enums
  • Produces comprehensive .pyi files for IDE consumption

The generated stubs provide full autocompletion and documentation in modern Python IDEs like VS Code, PyCharm, etc.

Trade-offs and Alternatives

Trade-offs:

  • Adds ~6 seconds to generate full documentation (but as separate optional target)
  • Increases repository size slightly with documentation files

Alternatives considered:

  • External documentation parsing libraries (rejected to minimize dependencies)
  • Manual stub file maintenance (rejected due to maintenance burden)
  • No documentation extraction (rejected as it provides significant developer value)

The implementation uses custom regex-based Doxygen parsing to avoid external dependencies while providing exactly the functionality needed for LVGL's documentation format.

andrewleech avatar Jun 06 '25 12:06 andrewleech

Thanks for the feedback, though I must admit you caught me off guard. I left this PR in draft because I intended to do a manual cleanup before prompting for discussion.

Yes this has been put together with significant assistance from Claude Code AI, I have been getting very high quality code design acceleration with it both professionally and on open source work.

This PR is actually the first in a string of improvements I've been intermittently working on; these stubs after intended to help developers certainly, but I also used them as an input for Claude to reference in a follow up branch to fix and modernise the examples and bring them all up to valid v9 syntax.

andrewleech avatar Jul 14 '25 08:07 andrewleech