"_rp2" module is not being merged correctly with docstrings

[samskiter]

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)

[samskiter]

I've attampted a fix for this here:

https://github.com/markb139/micropython/pull/1

[Josverl]

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.

https://github.com/Josverl/micropython-stubber/pull/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?

[samskiter]

That sounds like a good plan! Appreciate the effort to do this 'the right way'😃

On Sun, 12 Nov 2023, 13:56 Jos Verlinde, @.***> wrote:

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.

— Reply to this email directly, view it on GitHub https://github.com/Josverl/micropython-stubs/issues/727#issuecomment-1807136858, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJWOWYF2ANI4LIHWPAFQWDYEDIPDAVCNFSM6AAAAAA6YARPSKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMBXGEZTMOBVHA . You are receiving this because you authored the thread.Message ID: @.***>

[samskiter]

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

[Josverl]

@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

[samskiter]

Fab thanks! Having a bit micropython day tomorrow so will try and report back!