Implement the editable debugging tips as a reference to the docs.

Author: jaraco

docs/userguide/development_mode.rst

@@ -229,6 +229,25 @@ More information is available on the text of :pep:`PEP 660 <660#what-to-put-in-t
    used.
 
 
+Debugging Tips
+--------------
+
+If encountering problems installing a project in editable mode,
+follow these recommended steps to help debug:
+
+- Try to install the project normally, without using the editable mode.
+  Does the error still persist?
+  (If it does, try fixing the problem before attempting the editable mode).
+- When using binary extensions, make sure all OS-level
+  dependencies are installed (e.g. compilers, toolchains, binary libraries, ...).
+- Try the latest version of setuptools (maybe the error was already fixed).
+- When the project or its dependencies are using any setuptools extension
+  or customization, make sure they support the editable mode.
+
+After following the steps above, if the problem still persists and
+you think this is related to how setuptools handles editable installations,
+please submit a `reproducible example <https://stackoverflow.com/help/minimal-reproducible-example>`_ at `the bug tracker <https://github.com/pypa/setuptools/issues>`_.
+
 ----
 
 .. rubric:: Notes

setuptools/command/editable_wheel.py

@@ -29,10 +29,10 @@
 
 from .. import Command, _normalization, _path, _shutil, errors, namespaces
 from .._path import StrPath
-from ..compat import py312
+from ..compat import py310, py312
 from ..discovery import find_package_path
 from ..dist import Distribution
-from ..warnings import InformationOnly, SetuptoolsDeprecationWarning, SetuptoolsWarning
+from ..warnings import InformationOnly, SetuptoolsDeprecationWarning
 from .build import build as build_cls
 from .build_py import build_py as build_py_cls
 from .dist_info import dist_info as dist_info_cls
@@ -137,13 +137,14 @@ def run(self) -> None:
             bdist_wheel.write_wheelfile(self.dist_info_dir)
 
             self._create_wheel_file(bdist_wheel)
-        except Exception:
+        except Exception as ex:
             project = self.distribution.name or self.distribution.get_name()
-            if os.environ.get('SETUPTOOLS_INTERNAL_DEBUG'):
-                traceback.print_exc()
-                _DebuggingTips.emit(project=project)
-            else:
-                print("An error occurred building editable wheel for", project)
+            py310.add_note(
+                ex,
+                f"An error occurred when building editable wheel for {project}.\n"
+                "See debugging tips in: "
+                "https://setuptools.pypa.io/en/latest/userguide/development_mode.html#debugging-tips",
+            )
             raise
 
     def _ensure_dist_info(self):
@@ -905,29 +906,3 @@ def _finder_template(
 
 class LinksNotSupported(errors.FileError):
     """File system does not seem to support either symlinks or hard links."""
-
-
-class _DebuggingTips(SetuptoolsWarning):
-    _SUMMARY = "Problem in editable installation."
-    _DETAILS = """
-    An error happened while installing `{project}` in editable mode.
-
-    The following steps are recommended to help debug this problem:
-
-    - Try to install the project normally, without using the editable mode.
-      Does the error still persist?
-      (If it does, try fixing the problem before attempting the editable mode).
-    - If you are using binary extensions, make sure you have all OS-level
-      dependencies installed (e.g. compilers, toolchains, binary libraries, ...).
-    - Try the latest version of setuptools (maybe the error was already fixed).
-    - If you (or your project dependencies) are using any setuptools extension
-      or customization, make sure they support the editable mode.
-
-    After following the steps above, if the problem still persists and
-    you think this is related to how setuptools handles editable installations,
-    please submit a reproducible example
-    (see https://stackoverflow.com/help/minimal-reproducible-example) to:
-
-        https://github.com/pypa/setuptools/issues
-    """
-    _SEE_DOCS = "userguide/development_mode.html"

setuptools/compat/py310.py

@@ -7,3 +7,14 @@
     import tomllib
 else:  # pragma: no cover
     import tomli as tomllib
+
+
+if sys.version_info >= (3, 11):
+
+    def add_note(ex, note):
+        ex.add_note(note)
+
+else:  # pragma: no cover
+
+    def add_note(ex, note):
+        vars(ex).setdefault('__notes__', []).append(note)

setuptools/tests/test_editable_install.py

@@ -21,7 +21,6 @@
 
 from setuptools._importlib import resources as importlib_resources
 from setuptools.command.editable_wheel import (
-    _DebuggingTips,
     _encode_pth,
     _find_namespaces,
     _find_package_roots,
@@ -1201,9 +1200,9 @@ def test_debugging_tips(tmpdir_cwd, monkeypatch):
     simulated_failure = Mock(side_effect=SimulatedErr())
     monkeypatch.setattr(cmd, "get_finalized_command", simulated_failure)
 
-    expected_msg = "following steps are recommended to help debug"
-    with pytest.raises(SimulatedErr), pytest.warns(_DebuggingTips, match=expected_msg):
+    with pytest.raises(SimulatedErr) as ctx:
         cmd.run()
+    assert any('debugging-tips' in note for note in ctx.value.__notes__)
 
 
 @pytest.mark.filterwarnings("error")