Closed Josverl closed 7 months ago
As discussed in Discord with @Josverl, but for anyone else who might be following this, I've been working this week on converting the "source of truth" for the built-in MicroPython modules to stub files, using the micropython-stubber generated stubs as a starting point.
This is inspired by the Pybricks project, where their Sphinx documentation is generated from their stubs. See e.g. https://github.com/pybricks/pybricks-api/blob/master/src/pybricks/hubs.py which generates https://docs.pybricks.com/en/stable/hubs/index.html
So going forward, the main MicroPython repo will include stub files containing full type annotations, positional/kw arg indicators, overloads, and doc strings (now updated to be in "Google" format as supported by the Sphinx "napoleon" plugin), as well as annotations about which ports/boards/configurations given modules/classes/methods are supported on. I am also looking at including an "added in version" annotation. Initially this will include stdlib & micropython-specific built-ins (i.e. everything we currently have documentation for), and will eventually grow to include all of micropython-lib.
These stubs should be able to be used directly, but also as a machine-readable input to a project like this that publishes stubs for general use. For example, Pybricks also do this (using "jedi") to convert "Google" to "NumPy" docstrings. One thing you could do for example is filter the stubs to only include what's relevant for a given port/board.
I'll post a WIP PR in the next week or so and update this issue. It's slow progress, 5 modules done, ~85 to go.
Looking forward to seeing the initial versions
This was implemented in #9069 and #11740:
import umodule
still also works as a backwards-compatible way of forcing a built-in.Originally posted by @jimmo in https://github.com/micropython/micropython/issues/9018#issuecomment-1619338544