DOC: Add section on debugging Python wrappings

[tbirdso]

Add subsection for discussion of ITK Python debugging workflow based on @brad-t-moore 's internal presentation and upcoming blog post.

[tbirdso]

I've verified debugging steps with Python's pdb module as well as stepping through ITK files via RelWithDebInfo build debug symbols in Visual Studio on Windows. Confirmation of equivalent workflow using gdb on Linux is pending, currently waiting for ITK to finish building.

[tbirdso]

Pinging @thewtex and @brad-t-moore for review, comments, revisions, etc

[tbirdso]

I'm waiting for ITK to build so that I can verify whether the apt-get install python<version>-dbg step is actually required on Linux, but otherwise have confirmed that I can step through ITK and SWIG-generated source code on both Windows and Linux using the described process. If this step is not required I will remove it before merge.

EDIT: Verified that debug symbols are generated in RelWithDebInfo build without need for python<version>-dbg. Updated.

[thewtex]

@tbirdso fantastic work!

A few suggestions inline.

[dzenanz]

@tbirdso ping me after you amend with Matt's suggestions.

[jhlegarreta]

Have not gone through the details/would not be able to test them, and sorry to chime in. Thanks for doing this @tbirdso 🥇 . A few of notes:

• I am not sure about how consistent we have been indenting the LaTeX enumerate/itemize, lists, but I think it is preferable not to indent them for the sake of readability. Also, given that we do not have a style enforcing, it might be more consistent not to indent. We also gain room (the line width gets actually checked).
• I'd advocate for adding labels to all section/subsection/subsubsection, etc. categories. Even if at the moment we may not need to cross-ref them, they might be useful at some point.
• I'd (try to) provide a more development or architecture vs. debugging focus to the content, maybe slightly rephrasing section names or re-thinking some of the wording used. As it stands now (e.g. Strategies for Resolving Issues in Wrapped Classes, and mentions to debugger -I confess that this last might be necessary), parts of it might be more fit for a section in ITK's CONTRIBUTING.md, as some sort of FAQ, debugging (i.e. resolving issues), or troubleshooting section**. So maybe slightly re-wording the relevant section names or used wording might help in providing the necessary development (vs. debugging) focus to the section. I acknowledge that it might be hard to do this.

** I confess that other sections might exist in the ITK SW Guide that are also intended for similar purposes (most notably, the git workflow one, that's my fault).

[tbirdso]

Thanks for weighing in @jhlegarreta, glad to have your feedback!

• I can remove indentations and add labels to the sections in the scope of this PR. There is some inconsistency in how this is handled throughout the file, but I think that's best addressed in another PR if at all, given that it doesn't translate to the final PDF.
• You're right, it is hard to balance the architecture vs debugging discussion here as neither one is quite as useful without the other. This section gets deeper into the weeds than CONTRIBUTING.md currently does, and I would argue that the level of detail required to explain wrapping debugging steps makes the software guide a better fit, at least in the absence of a dedicated troubleshooting chapter. I'd be happy to make a similar debugging post on the community discourse where active ITK troubleshooting is happening, though codifying this section in the software guide will make sure it doesn't get lost or buried over time. There's also a technical blog post in the works to help disseminate this information for developers. I'll think on how we can change section titles to fit better with the rest of the guide.

[jhlegarreta]

I can remove indentations and add labels to the sections in the scope of this PR. There is some inconsistency in how this is handled throughout the file, but I think that's best addressed in another PR if at all, given that it doesn't translate to the final PDF.

OK.

I'd be happy to make a similar debugging post on the community discourse where active ITK troubleshooting is happening

Not necessary IMHO. A link to the section or eventual blog post would suffice in discourse to avoid redundancy.

though codifying this section in the software guide will make sure it doesn't get lost or buried over time.

👌.

There's also a technical blog post in the works to help disseminate this information for developers.

That's awesome 💯.

[thewtex]

@hjmjohnson and @seanm are macOS experts and may have guidance for attaching or debugging core dumps.

[brad-t-moore]

Sorry for my ignorance here- is there a way to see the generated output through git or do I need to checkout this PR and build locally?

-Brad

[tbirdso]

Good question @brad-t-moore , you can download the PDFs generated by CI under "Artifacts" from the run:
https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/actions/runs/1554481810

[tbirdso]

For the record, I didn't knowingly "dismiss" anything...

[tbirdso]

Added MacOS debugging steps (thanks to @thewtex for the use of the misty machine and @timthirion for the brief use of his laptop 😃 )

@hjmjohnson @seanm If you have an opportunity I would welcome your review on the MacOS side, am happy to revise based on your development experience.

@brad-t-moore please also let me know if you have thoughts/revisions on the debugging process per your own investigations

Other reviews welcome as always. Thanks!

[tbirdso]

Squashed changes.

[tbirdso]

I do not have write access to this repo -- could @dzenanz or @thewtex merge when ready?

[tbirdso]

Thank you @dzenanz !

[thewtex]

🐛 🍾 🎅