Add documentation for running oslo_debug_heler.sh

Removed inline comments from the shell file and added them to
the developer docs.

Change-Id: Iac0f969165883e173389a42e1bd1b0bc5d513553

doc/source/features.rst

@@ -0,0 +1,37 @@
+==========
+ Features
+==========
+
+Debugging with oslo_debug_helper.sh
+===================================
+
+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
+with `pdb <https://docs.python.org/2/library/pdb.html>`_.
+
+Adding breakpoints to the code
+------------------------------
+
+The typical usage to break into the debugger from a running program is to
+insert:
+
+.. code-block:: python
+
+  import pdb; pdb.set_trace()
+
+Update tox.ini
+--------------
+
+Within the ``tox.ini`` file of your project add the following::
+
+  [testenv:debug]
+  commands = oslo_debug_helper.sh {posargs}
+
+To run with tox:
+
+.. code-block:: bash
+
+  $ tox -e debug
+  $ tox -e debug test_notifications
+  $ tox -e debug test_notifications.NotificationsTestCase
+  $ tox -e debug test_notifications.NotificationsTestCase.test_send_notification

doc/source/index.rst

@@ -18,6 +18,7 @@ Contents
    installation
    api
    testing
+   features
    contributing
 
 Indices and tables

tools/oslo_debug_helper.sh

@@ -1,15 +1,5 @@
 #!/bin/bash
 
-# To utilize this file, add the following to tox.ini:
-#[testenv:debug]
-#commands = oslo_debug_helper.sh {posargs}
-
-# To run with tox:
-#tox -e debug
-#tox -e debug test_notifications
-#tox -e debug test_notifications.NotificationsTestCase
-#tox -e debug test_notifications.NotificationsTestCase.test_send_notification
-
 TMP_DIR=`mktemp -d` || exit 1
 trap "rm -rf $TMP_DIR" EXIT