Napari debugging during plugin development documentation

[seankmartin]

Description

This PR adds a page to the the napari.org/plugins category about debugging plugins during development.

Type of change

• Documentation update

References

closes #2948 closes #3735

Forum references:

• Tracebacks on Image.sc.
• Reloading changed code on Image.sc.
• Plugging logging on zulipchat

Here is the code used in the docs

How has this been tested?

• I manually checked that the code in the docs runs as expected.
• make docs runs successfully and builds the docs as expected.

Final checklist:

• My PR is the minimum possible work for the desired functionality
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• If I included new strings, I have used trans. to make them localizable.
  For more information see our translations guide.

[seankmartin]

Hi all, please let me know what you think of this draft documentation for debugging during plugin development. I'm very open to any feedback and really appreciate it!
@DragaDoncila thank you!

[github-actions]

Click here to download the docs artifacts
docs
(zip file)

[DragaDoncila]

This is looking great @seankmartin, thank you so much for writing such a detailed doc 🎉 ! I've left a couple of small tweaky comments and a couple just requesting a few notes added.

Let me know if I can clarify anything!

[seankmartin]

Hi @DragaDoncila thank you so much for the detailed review, that's brilliant!

I have incorporated all of the changes 😄.

I guess the main things to double check I understood correctly:

1. You asked for a few "notes". I wasn't sure if that meant to add a bit more detail, or specifically add note blocks (like {note}). I defaulted to just adding some extra explanatory text - but very happy to convert to note blocks if that is better.
2. I provided a link to the starting version of the code, it has all the contents of the long form code blocks I wrote out for plugin example setup. And a link to the finished version. Hopefully this works, but I understand this is a link to a personal repository so I'm fully open to any thoughts here!

Thank you again, and very happy to make further changes or discuss further.

[seankmartin]

Just looking at my built docs, it seems that linking to the markdown docs didn't work in this case (Line 28):
Your entry point is correctly configured, see the first steps for information.
Do we need to link to the html in this case?

[github-actions]

Click here to download the docs artifacts
docs
(zip file)

[github-actions]

Click here to download the docs artifacts
docs
(zip file)

[DragaDoncila]

@seankmartin thank you for those updates, it's looking great!

I defaulted to just adding some extra explanatory text - but very happy to convert to note blocks if that is better.

Extra text is perfect! I should be more specific with my terms lol.

Hopefully this works, but I understand this is a link to a personal repository so I'm fully open to any thoughts here!

Hmm yeah, we don't really have a standardized solution for this. I think for now it's ok if it points to your personal one, but we probably want to provide a more general mechanism in the future. I don't think that should hold up this PR though.

Just looking at my built docs, it seems that linking to the markdown docs didn't work in this case (Line 28):

Hmm yeah I'm not sure why that anchor link isn't working, I foolishly thought it might be the .md suffix but that hasn't fixed it. @melissawm do you know why this relative link isn't building?

[psobolewskiPhD]

I'm not 100% sure, but I ran into something similar. Perhaps try:
first_plugin.md#update-setup-cfg
So use the .md extension, but without the ./

[github-actions]

Click here to download the docs artifacts
docs
(zip file)

[DragaDoncila]

Hmm thanks for the suggestion @psobolewskiPhD, that doesn't seem to have worked either though.

[melissawm]

I left a few comments, hope those are useful - let me know if I can help further!

[seankmartin]

I left a few comments, hope those are useful - let me know if I can help further!

Hi @melissawm that's great, thank you so much for the help, much appreciated! 🎉

I was wondering, how do you find errors with the MyST parser? I built the docs locally before PR, but didn't notice the errors. Are there logs somewhere that you can check, or a command to run to find errors?

[melissawm]

@seankmartin the errors appear in the log of the docs build. Unfortunately we also get 300 other unrelated errors that mostly come from autosummary and the way it doesn't know how to deal with the napari codebase (this is autosummary's fault, not napari's!). Because I already know where to look, I can catch them in the sea of red messages 😅

[seankmartin]

@melissawm Thanks for the explanation, no wonder I didn't spot them! 😰

[seankmartin]

Just thinking about it now, I think I may have misunderstood the last suggestion regard the txt labelled code block that was causing issues. I'll have a look tomorrow, but I think the way I took the suggestion was not as intended.

[seankmartin]

Hi @melissawm I think I have fixed the myst parser errors/warnings now, though perhaps I am still looking in the wrong place in the logs!

Is this good to go if I have correctly fixed the myst parser errors/warnings? Please let me know if further changes are desired!