Document limitations for debugging as well as a workaround (#867)

Closes #863

Author: ralokt

Diff for: changelog/863.doc

@@ -0,0 +1 @@
+Document limitations for debugging due to standard I/O of workers not being forwarded. Also, mention remote debugging as a possible workaround.

Diff for: docs/known-limitations.rst

@@ -62,3 +62,10 @@ The ``-s``/``--capture=no`` option is meant to disable pytest capture, so users
 However, this option does not work with ``pytest-xdist`` because `execnet <https://github.com/pytest-dev/execnet>`__ the underlying library used for communication between master and workers, does not support transferring stdout/stderr from workers.
 
 Currently, there are no plans to support this in ``pytest-xdist``.
+
+Debugging
+~~~~~~~~~
+
+This also means that debugging using PDB (or any other debugger that wants to use standard I/O) will not work. The ``--pdb`` option is disabled when distributing tests with ``pytest-xdist`` for this reason.
+
+It is generally likely best to use ``pytest-xdist`` to find failing tests and then debug them without distribution; however, if you need to debug from within a worker process (for example, to address failures that only happen when running tests concurrently), remote debuggers (for example, `python-remote-pdb <https://github.com/ionelmc/python-remote-pdb>`__ or `python-web-pdb <https://github.com/romanvm/python-web-pdb>`__) have been reported to work for this purpose.