update documentation for new feature

changelog/3180.feature.rst

@@ -1,12 +1 @@
-Support for Python 3.7s builtin breakpoint() method.
+Support for Python 3.7's builtin ``breakpoint()`` method, see :ref:`breakpoint-builtin` for details.
-
-When breakpoint() is called and PYTHONBREAKPOINT is set to the default value,
-PyTest will use the Custom PDB trace UI instead of the system default Pdb.
-
-When tests are complete, the system will default back to the system Pdb trace UI.
-
-If --pdb is called on execution of Pytest, the custom Pdb interface is used on both
-breakpoint() and failed tests/unhandled exceptions.
-
-If --pdbcls is used, the custom class will be executed when a test fails (as expected within existing behaviour),
-but also when breakpoint() is called from within a test, the custom class debugger will be instantiated.

doc/en/usage.rst

@@ -189,6 +189,21 @@ in your code and pytest automatically disables its output capture for that test:
   for test output occurring after you exit the interactive PDB_ tracing session
   and continue with the regular test run.
 
+
+.. _breakpoint-builtin:
+
+Using the builtin breakpoint function
+-------------------------------------
+
+Python 3.7 introduces a builtin ``breakpoint()`` function. 
+Pytest supports the use of ``breakpoint()`` with the following behaviours:
+
+ - When breakpoint() is called and PYTHONBREAKPOINT is set to the default value, PyTest will use the Custom PDB trace UI instead of the system default Pdb.
+ - When tests are complete, the system will default back to the system Pdb trace UI.
+ - If --pdb is called on execution of Pytest, the custom Pdb interface is used on both
+breakpoint() and failed tests/unhandled exceptions.
+ - If --pdbcls is used, the custom class will be executed when a test fails (as expected within existing behaviour), but also when breakpoint() is called from within a test, the custom class debugger will be instantiated.
+
 .. _durations:
 
 Profiling test execution duration