Improve debugging instructions

[TimMonko]

📚 New content request

For developing napari, I have slowly tried to figure out the debugger, because it helps when I can't figure out where an untyped inheritance is coming from. But, debugging still confuses me. There is documentation in building a plugin on debugging but it doesn't seem as helpful (or at least as understandable) as I'd like.

This will help new contributors be able to navigate quirks of the architecture more quickly.

I'm still confused, but would be happy to look over any PRs that people make on this topic.

Outline

[Czaki]

Hi,
At first, please use link to napari website, not local version of documentation. I think that you would like to point to https://napari.org/dev/plugins/building_a_plugin/debug_plugins.html

At second. It will be nice if you describe your problem, for which you could not find help. Otherwise, we do not know if we need to rephrase/improve some part of the documentation, or add new content.

[TimMonko]

@Czaki, my apologies for the bad link-- guess I wasn't paying enough attention. I've fixed it to point to the same place you linked to.

I think what I am looking for is new content that gives tips on how to use debugger to understand things like napari events and how things like components, vispy, qt, etc are all inheriting things. At the one community meeting, you quickly showed it in use with a super.__init__() breakpoint, and while I think maybe I got that to work, I also didn't get nearly as much information out of it as you seemed to. I tried to do my own reading on setting up debugging, which was successful. But I feel like I have a skill gap between 'this is how to set up debugging' and 'this is how to use debugging to understand napari'.

Again, it's not something that is napari specific, but if napari wants new intermediate-level contributors, this would really help with that.

[psobolewskiPhD]

I think for sure we should add debugging to https://napari.org/stable/developers/index.html#contributing
It's not obvious why a napari user would need to look in the plugin docs for debugging info.
I think the plugin docs are a good start, I'd consider just adapting those as a start?

I'd love to get better at it myself, rather than print statements 👀
My understanding is the main napari specific thing that is not obvious thing is you need to write a script to launch napari but set break points in napari.

But beyond that it's pretty generally applicable?
So then maybe y'all have some resources for debugging? It would be nice not to duplicate things from other sources if they are generally applicable -- lowers the maintenance burden.

[Czaki]

Maybe as a good starting point:
https://gitlab.mimuw.edu.pl/python-tools/debugger
http://lectures.scientific-python.org/advanced/debugging/index.html

As I currently understand, the request is about a generic debugging tutorial, not connected to napari, and then a few remarks (like use stack information to detect from where a function is triggered, inspect events to detect what is connected to it)?

Maybe we should first look for other scientific projects, if they do have such resources? If not, maybe we should even consider applying to NumFocus SDG for preparing such materials. At least for me, it will be multiple hours to prepare high-quality materials covering at least PyCharm and VSCode. And it will require multiple review hours.

[TimMonko]

I'd love to get better at it myself, rather than print statements 👀
My understanding is the main napari specific thing that is not obvious thing is you need to write a script to launch napari but set break points in napari.

prints are still great! But yes, I think the script is part of the missing link for me. I'm pretty sure I've done that and had it not work, and other times have had it work, so I'm not doing something quite right there.

Maybe as a good starting point:
https://gitlab.mimuw.edu.pl/python-tools/debugger
http://lectures.scientific-python.org/advanced/debugging/index.html

I'll work through these in the near future and give feedback on how helpful they are. but even just linking this general advice would be such a benefit!

As I currently understand, the request is about a generic debugging tutorial, not connected to napari, and then a few remarks (like use stack information to detect from where a function is triggered, inspect events to detect what is connected to it)?

This is EXACTLY what I'm looking for! 😄

[DragaDoncila]

Yeah I think this would be super useful to have. I live in debug mode for napari and once you get the hang of it, it's crazy how much easier it is than printing - although I'll still sometimes do a cheeky print here and there.

Bonus screenshot cause I'm in the debugger as we speak with a print statement to boot.

[psobolewskiPhD]

Thanks @Czaki !
I think we should make a debugging page in the contributor section with getting napari running editable and under debugging in an IDE (can prolly copy paste from the plugin section? I'd never think to look there as a not-a-plugin-author).
And we include those links to broader resources plus any other tips y'all have.