Add basic debug doc

docs/html/reference/index.rst

@@ -17,3 +17,4 @@ Reference Guide
    pip_config
    pip_wheel
    pip_hash
+   pip_debug

docs/html/reference/pip_debug.rst

@@ -0,0 +1,28 @@
+.. _`pip debug`:
+
+pip debug
+-----------
+
+.. contents::
+
+Usage
+*****
+
+.. pip-command-usage:: debug
+
+
+.. warning::
+    This command is only meant for debugging.
+    Its options and outputs are provisional and may change without notice.
+
+
+Description
+***********
+
+.. pip-command-description:: debug
+
+
+Options
+*******
+
+.. pip-command-options:: debug

docs/man/commands/debug.rst

@@ -0,0 +1,26 @@
+:orphan:
+
+==========
+pip-debug
+==========
+
+Description
+***********
+
+.. pip-command-description:: debug
+
+Usage
+*****
+
+.. pip-command-usage:: debug
+
+
+.. warning::
+    This command is only meant for debugging.
+    Its options and outputs are provisional and may change without notice.
+
+
+Options
+*******
+
+.. pip-command-options:: debug

src/pip/_internal/commands/debug.py

@@ -91,6 +91,12 @@ def __init__(self, *args, **kw):
 
     def run(self, options, args):
         # type: (Values, List[Any]) -> int
+        logger.warning(
+            "This command is only meant for debugging. "
+            "Do not use this with automation for parsing and getting these "
+            "details, since the output and options of this command may "
+            "change without notice."
+        )
         show_value('pip version', get_pip_version())
         show_value('sys.version', sys.version)
         show_value('sys.executable', sys.executable)

tests/functional/test_debug.py

@@ -15,7 +15,7 @@ def test_debug(script, args):
     Check simple option cases.
     """
     args = ['debug'] + args
-    result = script.pip(*args)
+    result = script.pip(*args, allow_stderr_warning=True)
     stdout = result.stdout
 
     assert 'sys.executable: ' in stdout
@@ -43,7 +43,7 @@ def test_debug__target_options(script, args, expected):
     Check passing target-related options.
     """
     args = ['debug'] + args
-    result = script.pip(*args)
+    result = script.pip(*args, allow_stderr_warning=True)
     stdout = result.stdout
 
     assert 'Compatible tags: ' in stdout