Integrate hlovatt's alternate stubs for MicroPython

[Josverl]

Integrate hlovatt's alternate stubs for MicroPython that contain types and docs? Not sure if your project to generate stubs is still active?

Howard has generated some at PyBoardTypeshed.

The generators are at PyBoardTypeshedGenerator. The generators scrape the MicroPython .rst files, rather than run on the boards themselves.

[jdtsmith]

Strong vote yes! I tried the PyBoardTypeshed with my esp32 project, and it's already a big improvement. Definitely some changes to network, uos, etc., but so far so good. @hlovatt, I wonder how easy this is to adapt to other ports (like esp32)?

[Josverl]

I did look at Howard's code , but i did not see a way to automate/extend this to other ports and modules that did not involve a lot of effort. As I understand it, Howard's solution 'pulls-in' the relevant info form the documentation, which gives a lot of flexibility.

In https://github.com/Josverl/micropython-stubber/issues/30 i have taken a different approach, I iterate over and (clumsily)parse the RST files, and then directly generate stub modules from that. This does require a bit of guessing, a bit of searching , and a few lookup tables and some minor updates/fixes to the source documentation. but anytime the documentation gets updates and improvments, the stubs also update/improve. still the quality is lower than handcrafted solutions such as Howards , and such as PicoPy for the RP2 where the documentation quality is not too good (yet)

[hlovatt]

Glad you found the stubs useful. I will take a look at how hard it is to add esp32.

[jdtsmith]

Thanks both. It's too bad people don't start with stubs for documenting, and then parse them for the RST files.

[hlovatt]

My long term plan is:

• See if the MicroPython folks will adopt my typesheds as part of MicroPython.
• Assuming they do then see if they will accept replacing the current MicroPython docs with docs generate from the typesheds.

The purpose of this is that you would get official typesheds and improved documentation.

However need MicroPython developers to agree and have to work out how you go from typeshed -> rst.

[hlovatt]

@jdtsmith @Josverl Have added esp.pyi to https://github.com/hlovatt/PyBoardTypeshed. The only things are:

1. I don't use esp boards or even own one; therefore possibly mistakes in my understanding.

2. There were a number of undocumented functions; I've added some documentation - but not sure how good my documentation is!

   Any chance of trying it out and see if I've understood how the board works.

[jdtsmith]

Thanks @hlovatt. I took a look and in limited testing, so far so good.

The one issue I noticed is that in addition to the esp module, other modules are subtly and not-so-subtly changed on ESP32 MP port compared to other ports. Usually it's small things like the addition of network.STA_IF and AP_IF constants, but some larger differences, e.g. in machine there are additional classes DAC, SoftI2C, SoftSPI, and TouchPad on ESP32. If you take a look in these stubs you can get a sense of the differences. Perhaps between your and @Josverl's methods we could have the best of both approaches.

BTW, I noticed you are missing uasyncio.TimeoutError.

[hlovatt]

@jdtsmith @Josverl Have added TimoutError and also added ability to install from PyPI:

    pip install --upgrade micropython-typesheds
    python -m micropython-typesheds <destination-directory>

Will take a look at combining @Josverl technique with my own - its on my long term list of things to do!

[Josverl]

@hlovatt Howard, I'd love to sit down with a - insert favorite drink here - and work out a way to get the both of the multiple approaches. ( but I fear that is a 12 hour trip one way :-( ) I've been weighing the pro's and con's of the different methods of not only creating, but mostly maintaining stubs for some time now. Rather than trying to force a one size fits all approach - I try to combine the strengths of the different types of stubs. I tried to document this here : https://micropython-stubs.readthedocs.io/en/latest/15_order.html

[Josverl]

Also : recently added a new type of stubs ( doc Stubs) that generate docstubs directly off the micropython documentation as well . https://github.com/Josverl/micropython-stubs/tree/main/stubs/micropython-latest-docstubs the ccode to generate this is in : https://github.com/Josverl/micropython-stubber/blob/main/src/stubs_from_docs.py

Note: There are still a few (8) classes and functions and constants that have errors and omissions in the documentation that result in some errors, but since 1.16 the documentation is good enough for the majority of modules.
There is a PR open for that that has been acked by Damien, but is not completely merged.

[github-actions[bot]]

Stale issue message