From bd005c9a96b98fad6b5c0e33c28090b6c850b817 Mon Sep 17 00:00:00 2001 From: baldurk Date: Wed, 12 Aug 2026 11:07:52 +0100 Subject: [PATCH] Add clarification on the workflow for attaching python debugger --- docs/python_api/faq.rst | 2 ++ docs/python_api/ide_integration.rst | 9 +++++++++ 2 files changed, 11 insertions(+) diff --git a/docs/python_api/faq.rst b/docs/python_api/faq.rst index 121718ce5..d32f4f972 100644 --- a/docs/python_api/faq.rst +++ b/docs/python_api/faq.rst @@ -102,6 +102,8 @@ If you find that script files open in a new tab even if the file is already open If exceptions are not being caught by VS Code, make sure you have the ``User Uncaught Exceptions`` setting under ``Breakpoints`` enabled, as RenderDoc itself catches otherwise-uncaught exceptions when running python code to improve UI stability and so VS Code's unhandled exception handler will not usually catch them. +RenderDoc only listens on one fixed port for the python debugger, so if you have multiple instances of RenderDoc's UI open only the first one to launch will be able to debug python code. + .. _example_preamble: Why do the examples have a preamble for ``pyrenderdoc``? diff --git a/docs/python_api/ide_integration.rst b/docs/python_api/ide_integration.rst index 6fc476559..73ae0fc64 100644 --- a/docs/python_api/ide_integration.rst +++ b/docs/python_api/ide_integration.rst @@ -82,6 +82,15 @@ If RenderDoc has detected your installation of VS Code it also provides convenie .. warning:: By default, RenderDoc creates a :file:`.vscode` folder and :file:`launch.json` configuring the debugging setup for attaching, but it will not overwrite an existing file. Be warned that VS Code's default remote attach configuration contains "path mappings" which can cause RenderDoc debugging to not function correctly, since remote attach is normally not used on the same folder. It is strongly recommended you delete any path mappings and restart RenderDoc & VS Code if you have already tried to attach. +Debugging workflow +------------------ + +When using an external python debugger such as VS Code, it can be attached to the RenderDoc UI at any time as long as RenderDoc has detected or been configured for the appropriate ``debugpy`` module. Attaching must be initiated from the IDE side and can't be started from RenderDoc - the attach debugger button within RenderDoc's UI only launches the IDE and possibly triggers it to attach immediately, but is not necessary if you already have your IDE open. + +When attached, the external debugger will debug all python code in RenderDoc even if it has a project open that only contains e.g. one script or one UI extension. You can reattach at any time from the relevant project, with nothing needed on the RenderDoc side. + +RenderDoc's python debugger connection is singleton though so only one IDE/debugger can be attached at a time, and only the first instance of the UI to start will be available to connect to. + Next steps ----------