gh-93103: Enhance PyConfig.parser_debug documentation (#93186)

vstinner · web-flow · commit c7667a2d353c · 2022-05-24T23:23:01.000+02:00
Document that -d option and PYTHONDEBUG env var require a debug
build of Python. Also mention them in the debug build documentation.
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
@@ -986,6 +986,9 @@ PyConfig
       Incremented by the :option:`-d` command line option. Set to the
       :envvar:`PYTHONDEBUG` environment variable value.
 
+      Need a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
+      must be defined).
+
       Default: ``0``.
 
    .. c:member:: int pathconfig_warnings
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
@@ -248,8 +248,11 @@ Miscellaneous options
 
 .. cmdoption:: -d
 
-   Turn on parser debugging output (for expert only, depending on compilation
-   options).  See also :envvar:`PYTHONDEBUG`.
+   Turn on parser debugging output (for expert only).
+   See also the :envvar:`PYTHONDEBUG` environment variable.
+
+   This option requires a :ref:`debug build of Python <debug-build>`, otherwise
+   it's ignored.
 
 
 .. cmdoption:: -E
@@ -660,6 +663,9 @@ conflict.
    :option:`-d` option.  If set to an integer, it is equivalent to specifying
    :option:`-d` multiple times.
 
+   This environment variable requires a :ref:`debug build of Python
+   <debug-build>`, otherwise it's ignored.
+
 
 .. envvar:: PYTHONINSPECT
 
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
@@ -278,6 +278,8 @@ Effects of a debug build:
 * Add ``d`` to :data:`sys.abiflags`.
 * Add :func:`sys.gettotalrefcount` function.
 * Add :option:`-X showrefcount <-X>` command line option.
+* Add :option:`-d` command line option and :envvar:`PYTHONDEBUG` environment
+  variable to debug the parser.
 * Add support for the ``__lltrace__`` variable: enable low-level tracing in the
   bytecode evaluation loop if the variable is defined.
 * Install :ref:`debug hooks on memory allocators <default-memory-allocators>`
