Clean up the docs for oslo_debug_helper

Just a minor clean up to provide a bit more information and
clarity on how to run the debugger.

Change-Id: I3f128780e8420e4074f3ec4553019e1afb429eca

doc/source/features.rst

@@ -2,8 +2,8 @@
  Features
 ==========
 
-Debugging with oslo_debug_helper.sh
+Debugging with oslo_debug_helper
-===================================
+================================
 
 The oslotest package also distributes a shell file that may be used to assist
 in debugging python code. The shell file uses testtools, and supports debugging
@@ -28,9 +28,10 @@ Within the ``tox.ini`` file of your project add the following::
   commands = oslo_debug_helper {posargs}
 
 If the project name, and the module that precedes the tests directory do not
-match, then consider passing an argument to ``tox.ini``.
+match, then consider passing a `-t` argument to `oslo_debug_helper` to
+indicate the directory where tests are located.
 
-For example, ``python-keystoneclient`` project has tests in
+For example, the ``python-keystoneclient`` project has tests in
 ``keystoneclient/tests``, thus it would have to pass in::
 
   [testenv:debug]
@@ -42,7 +43,10 @@ would have to pass in::
   [testenv:debug]
   commands = oslo_debug_helper -t tests {posargs}
 
-To run with tox:
+Debugging with tox
+------------------
+
+To enable debugging, run tox with the ``debug`` environment:
 
 .. code-block:: bash
 
@@ -50,3 +54,11 @@ To run with tox:
   $ tox -e debug test_notifications
   $ tox -e debug test_notifications.NotificationsTestCase
   $ tox -e debug test_notifications.NotificationsTestCase.test_send_notification
+
+Which results in an interactive prompt:
+
+.. code-block:: bash
+
+  > /opt/stack/ceilometer/ceilometer/tests/identity/test_notifications.py(106)notification_for_role_change()
+  -> action_name = '%s.%s' % (action, ROLE_ASSIGNMENT)
+  (Pdb)