"_rp2" module is not being merged correctly with docstrings
Closed this issue · 6 comments
The rp2 module is split into two - rp2.py which is manually written and _rp2.py which is generated (I think) on the firmware board).
When running get-dosctubs, the docstubs are bring applied to rp2.py, not _rp2.py. rp2.py is later overwritten by frozen modules.
Frozen module pulls rp2.py from here: https://github.com/micropython/micropython/blob/master/ports/rp2/modules/rp2.py
Docstubs are generated from https://github.com/micropython/micropython/blob/master/docs/library/rp2.rst and https://raw.githubusercontent.com/micropython/micropython/master/docs/library/rp2.PIO.rst etc. In the latter you can see there is an attempt to associate it with _rp2.py but it doesn't seem to be working:
.. currentmodule:: rp2
.. _rp2.PIO:
I'm not sure therefore whether this is a bug of the stubber or whether the rst files should be fixed.
We can see though, that the docs never make it through to the published stubs: https://github.com/Josverl/micropython-stubs/blob/main/publish/micropython-latest-rp2-stubs/_rp2.pyi
But do make it through to docstubs: https://github.com/Josverl/micropython-stubs/blob/main/stubs/micropython-v1_21_0-docstubs/rp2.pyi albeit in the wrong file! (no _rp2.py file is generated)
I've attampted a fix for this here:
I do not think that changing the micropython docs this way is the correct approach
Some of the micropython modules are implemented partly in C and partly in Python, while the documentation does not always detail the implementation.
To compensate for this I've been writing some updates to stubber to apply the documentation for a module, also to its _variant.
That avoids needing to change the documentation, and also works for a few other modules that have been implemented using the same approach.
Josverl/micropython-stubber#448
I think that is the better solution.
I think in your changes to the micropython docs you have some other relevant improvements, but they are mixed in with a lot of other changes.
What would you like to do with those?
To be honest a lot of the changes in the PR are showing changes from master. Changes I have made are just here: https://github.com/markb139/micropython/pull/1/files/a4a9b682a3ce754ea1384b3332a62a6c857f5ccb..1006bc5e5015208d1e3dd89497a4bb3a48199d23
@samskiter,
I have updated the stubber tool and used that to update the typestubs, and the _rp2.pyi stub should now include the documentation where that could be matched.
I just release and published the updated stubs ( including the _rp2.pyi module) to PyPI,
so you can install / update as usual.
Please let me know if this works for you, and if there is anything missing.
| Micropython Version | Published Packages | Post Version |
|---|---|---|
| v1.21.0 | ||
| micropython-rp2-stubs | 1.21.0.post1 | |
| micropython-rp2-rpi_pico-stubs | 1.21.0.post2 | |
| micropython-rp2-rpi_pico_w-stubs | 1.21.0.post2 |
Fab thanks! Having a bit micropython day tomorrow so will try and report back!