Document Python configuration for embedded hosts

README.md

@@ -66,6 +66,14 @@ The following command will ignore subprocesses started by the debugged process.
 
 For full details, see the [API reference](https://github.com/microsoft/debugpy/wiki/API-Reference).
 
+### Embedded Python hosts
+`debugpy.listen()` uses `sys.executable` to start the debug adapter by default. If Python is embedded in another application, set the path to a Python interpreter before starting the listener:
+```python
+import debugpy
+debugpy.configure(python="/path/to/python")
+debugpy.listen(("localhost", 5678))
+```
+
 ### Enabling debugging
 At the beginning of your script, import debugpy, and call `debugpy.listen()` to start the debug adapter, passing a `(host, port)` tuple as the first argument.
 ```python

src/debugpy/public_api.py

@@ -76,6 +76,14 @@ def configure(__properties: dict[str, typing.Any] | None = None, **kwargs) -> No
     "attach" request, because they must be applied as early as possible
     in the process being debugged.
 
+    When Python is embedded in another application, ``sys.executable``
+    may point to the host executable instead of a Python interpreter. Set
+    the ``python`` property to the interpreter that debugpy should use to
+    start its adapter process, before calling ``listen``::
+
+        debugpy.configure(python="/path/to/python")
+        debugpy.listen(...)
+
     For example, a "launch" configuration with subprocess debugging
     disabled can be defined entirely in JSON::