From e7556d74c231a98a5e9a17adaa38a0526523c70d Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Tue, 28 Dec 2021 18:29:03 +0100
Subject: [PATCH] Better document remote debugging, add example

---
 MANIFEST.in              |  2 ++
 doc/starting.rst         | 18 +++++++++++++++---
 examples/remote-debug.py |  8 ++++++++
 3 files changed, 25 insertions(+), 3 deletions(-)
 create mode 100644 examples/remote-debug.py

diff --git a/MANIFEST.in b/MANIFEST.in
index 1bfde1d..b96b1e8 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -10,4 +10,6 @@ include doc/*.py
 include doc/conf.py
 include doc/images/*.png
 
+include examples/*.py
+
 include manual-tests/*.py
diff --git a/doc/starting.rst b/doc/starting.rst
index 58e2f8d..d819c53 100644
--- a/doc/starting.rst
+++ b/doc/starting.rst
@@ -70,7 +70,8 @@ instead, use the ``--log-errors`` flag::
 Remote debugging
 ^^^^^^^^^^^^^^^^
 
-Rudimentary remote debugging is also supported::
+Rudimentary remote debugging is also supported. To break into the debugger,
+enabling you to connect via ``telnet``, use the following code::
 
     from pudb.remote import set_trace
     set_trace(term_size=(80, 24))
@@ -78,9 +79,19 @@ Rudimentary remote debugging is also supported::
 At this point, the debugger will look for a free port and wait for a telnet
 connection::
 
-    pudb:6899: Please telnet into 127.0.0.1 6899.
+    pudb:6899: Please start a telnet session using a command like:
+    telnet 127.0.0.1 6899
     pudb:6899: Waiting for client...
 
+To debug a function in a remote debugger (and examine any exceptions that
+may occur), use code like the following:
+
+.. literalinclude:: ../examples/remote-debug.py
+
+Upon running this, again, the debugger will wait for a telnet connection.
+
+The following programming interface is available for the remote debugger:
+
 .. automodule:: pudb.remote
 
 "Reverse" remote debugging
@@ -138,7 +149,8 @@ Usage with pytest
 ^^^^^^^^^^^^^^^^^
 
 To use PuDB with `pytest <http://docs.pytest.org/en/latest/>`_, consider
-using the `pytest-pudb <https://pypi.python.org/pypi/pytest-pudb>`_ plugin.
+using the `pytest-pudb <https://pypi.python.org/pypi/pytest-pudb>`_ plugin,
+which provides a ``--pudb`` option that simplifies the procedure below.
 
 Alternatively, as of version 2017.1.2, pudb can be used to debug test failures
 in `pytest <http://docs.pytest.org/en/latest/>`_, by running the test runner
diff --git a/examples/remote-debug.py b/examples/remote-debug.py
new file mode 100644
index 0000000..a57cb1e
--- /dev/null
+++ b/examples/remote-debug.py
@@ -0,0 +1,8 @@
+def debugged_function(x):
+    y = x + fail  # noqa: F821
+    return y
+
+
+from pudb.remote import debugger
+dbg = debugger()
+dbg.runcall(debugged_function, 5)