Add documentation on ipython debugging #3579
Conversation
Signed-off-by: lrcouto <laurarccouto@gmail.com>
|
|
||
| Starting the debugger with either of the methods above will open an interactive shell where the user can navigate through the stack trace, inspect the value of expressions and arguments, or add breakpoints to the code. | ||
|
|
||
| [I think we should add some visual examples here, with images or maybe video showing the commands. Maybe add a cheat sheet. Maybe a command cheat sheet, which is easier to read than using the help function on the shell itself] |
There was a problem hiding this comment.
Agreed 👍🏽 a short GIF can go a long way
Signed-off-by: Ahdra Merali <90615669+AhdraMeraliQB@users.noreply.github.com>
|
|
||
| Example output: | ||
|
|
||
| ```ipython |
There was a problem hiding this comment.
Instead of static output can we include gifs instead? These can include the preceding command, as well as the result of using %debug
|
|
||
| Running `%pdb` before executing the program will enable the option to automatically start a debugger when an exception occurs. This behavior can be enabled with `%pdb 1` or `%pdb on`, and disabled with `%pdb 0` or `%pdb off`. | ||
|
|
||
| ### Interactive debugging with Ipython pdb |
There was a problem hiding this comment.
Unsure what this section adds to the documentation
|
|
||
| [I think we should add some visual examples here, with images or maybe video showing the commands. Maybe add a cheat sheet. Maybe a command cheat sheet, which is easier to read than using the help function on the shell itself] | ||
|
|
||
| ### Running and stopping on a specified breakpoint |
There was a problem hiding this comment.
I'd hesitate to include this section - whilst it is informative for notebook debugging, it feels unrelated to debugging Kedro projects, as we promote using session.run() instead of using %run to run the project's __main__.py.
Signed-off-by: Ahdra Merali <90615669+AhdraMeraliQB@users.noreply.github.com>
Signed-off-by: Ahdra Merali <ahdra.merali@quantumblack.com>
Signed-off-by: lrcouto <laurarccouto@gmail.com>
Signed-off-by: L. R. Couto <laurarccouto@gmail.com>
Signed-off-by: L. R. Couto <laurarccouto@gmail.com>
| @@ -236,6 +236,37 @@ If a Jupyter kernel with the name `kedro_<package_name>` already exists then it | |||
|
|
|||
| You can use the `jupyter kernelspec` set of commands to manage your Jupyter kernels. For example, to remove a kernel, run `jupyter kernelspec remove <kernel_name>`. | |||
|
|
|||
| ### Debugging with %debug and %pdb | |||
|
|
|||
There was a problem hiding this comment.
The first is a really long sentence, is there a way to shorten this, perhaps by using bullets? Also, maybe rewrite "Then, the user can inspect the value of expressions and arguments, or add breakpoints to the code." to something simpler like "You can then inspect the value of..."
There was a problem hiding this comment.
Few changes but looks good to me. The GIFs are rendering in the built docs (https://kedro--3579.org.readthedocs.build/en/3579/notebooks_and_ipython/kedro_and_notebooks.html) but they are a bit distracting in that there's a moving image.
I wonder if it would make sense to put them behind a <details>Click here<summary></summary></details> block so the user isn't distracted by them until they need to review them?
Signed-off-by: lrcouto <laurarccouto@gmail.com>
Co-authored-by: Jo Stichbury <jo_stichbury@mckinsey.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>
There was a problem hiding this comment.
Looks good so far!
Remember: We should remove the section "How to use tags to convert functions from Jupyter notebooks into Kedro nodes", see this commit. This functionality is outdated and no longer exists within 0.19.x
Co-authored-by: Ahdra Merali <90615669+AhdraMeraliQB@users.noreply.github.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>
Signed-off-by: lrcouto <laurarccouto@gmail.com>
There was a problem hiding this comment.
This looks amazing, thanks for addressing all the changes!
Just one thing - we'd likely be promoting use of this debug workflow as an alternative to using %load_node (e.g. if it's not supported). Is it possible to omit this from the gifs? Maybe using session.run() instead of %load_node split_data_node ? (Or still using the contents of split_data_node, but without showing the %load_node demo
Rethought this after looking at #2672 - I think it's better to keep the gifs as they are. No changes from me!
| You can use the `%debug` [line magic](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-debug) to launch an interactive debugger in your Jupyter notebook. Declare it before a single-line statement to step through the execution in debug mode. You can use the argument `--breakpoint` or `-b` to provide a breakpoint. | ||
| Running `%debug` immediately after an error has occurred will: | ||
| - Load the stack trace of the last unhandled exception. | ||
| - Stop the program at the point where the exception occurred. |
There was a problem hiding this comment.
Likewise for these two steps. Rephrase to remove passive tense if possible and match tense.
Co-authored-by: Jo Stichbury <jo_stichbury@mckinsey.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>
Co-authored-by: Jo Stichbury <jo_stichbury@mckinsey.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>
Co-authored-by: Jo Stichbury <jo_stichbury@mckinsey.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>
Co-authored-by: Jo Stichbury <jo_stichbury@mckinsey.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>
Co-authored-by: Jo Stichbury <jo_stichbury@mckinsey.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>
Signed-off-by: lrcouto <laurarccouto@gmail.com>
Applied the changes, thanks for the feedback! |
| @@ -14,7 +14,7 @@ This is a growing set of technical FAQs. The [product FAQs on the Kedro website] | |||
|
|
|||
| ## Working with Jupyter | |||
|
|
|||
| * [How can I convert functions from Jupyter Notebooks into Kedro nodes](../notebooks_and_ipython/kedro_and_notebooks.md#how-to-use-tags-to-convert-functions-from-jupyter-notebooks-into-kedro-nodes)? | |||
| * [How can I debug a Kedro project in a Jupyter notebook](../notebooks_and_ipython/kedro_and_notebooks.md#debugging-with-debug-and-pdb)? | |||
There was a problem hiding this comment.
This is fine for now, when we have all the content, I think it makes sense to have a page just talk about debugging.
It may included the content or just provide a link to:
- setup debugger in IDEs (link)
- Debugging in notebook with %load_node
- debugging in notebook with %debug %pdb
There are also debugger and breakpoints in jupyterlab (I expect works for notebook >7.0 too). %debug or %pdb works fine for checking quickly, but I wouldn't advise to use them to debug complex logic.
AhdraMeraliQB
dismissed
stichbury’s stale review
The requested changes have been made
Description
Adds a new section on the Notebooks and IPython page explaining how to use the
%debugand%pdbcommands to run the python debugger inside a notebook.Development notes
Developer Certificate of Origin
We need all contributions to comply with the Developer Certificate of Origin (DCO). All commits must be signed off by including a
Signed-off-byline in the commit message. See our wiki for guidance.If your PR is blocked due to unsigned commits, then you must follow the instructions under "Rebase the branch" on the GitHub Checks page for your PR. This will retroactively add the sign-off to all unsigned commits and allow the DCO check to pass.
Checklist
RELEASE.mdfile