[Zope3-checkins] SVN: Zope3/trunk/doc/DEBUG.txt restify document and update info (mention zopectl debug)

[Philipp von Weitershausen]

Log message for revision 37508:
  restify document and update info (mention zopectl debug)
  

Changed:
  U   Zope3/trunk/doc/DEBUG.txt

-=-
Modified: Zope3/trunk/doc/DEBUG.txt
===================================================================
--- Zope3/trunk/doc/DEBUG.txt	2005-07-27 22:48:36 UTC (rev 37507)
+++ Zope3/trunk/doc/DEBUG.txt	2005-07-27 23:03:31 UTC (rev 37508)
@@ -1,91 +1,109 @@
 Using the Zope Debugger
+=======================
 
-  Introduction
+Introduction
+------------
   
-    Zope3 includes a mechanism to debug an object publishing request, 
-    similar to the Zope2 
-    "debug mechanism":http://www.zope.org/Members/mcdonc/HowTos/UsingTheZopeDebugger
+Zope3 includes a mechanism to debug an object publishing request,
+similar to the `Zope 2 debug mechanism`_
 
-  Setting up Environment
+.. _Zoep 2 debug mechanism: http://www.zope.org/Members/mcdonc/HowTos/UsingTheZopeDebugger
 
-    Setup your PYTHONPATH environment variable to include
-    src. ie (unix bash syntax)::
 
-      cd Zope3
-      export PYTHONPATH=$PWD/src:$PYTHONPATH
+Setting up the environment
+--------------------------
+
+Setup your PYTHONPATH environment variable to include src. ie (unix
+bash syntax):
+
+  cd Zope3
+  export PYTHONPATH=$PWD/src:$PYTHONPATH
     
-    To start interacting with the debugger you need to initialize the
-    zope application::
+To start interacting with the debugger you need to initialize the zope
+application:
 
-      $ python2.3
-      >>> from zope.app.debug import Debugger
-      >>> debugger = Debugger()
+  $ python2.3
+  >>> from zope.app.debug import Debugger
+  >>> debugger = Debugger()
 
+Note that you can pass a database file name and a site ZCML file to
+the debugger:
 
-    Note that you can pass a database file name and a site ZCML file
-    to the debugger:
-
-      >>> Debugger('path/to/zodb/', 'path/to/site.zcml')
+  >>> Debugger('path/to/zodb/', 'path/to/site.zcml')
           
-    But you can generally let the debugger figure out where they are.
+But you can generally let the debugger figure out where they are.
+XXX In the future, the debugger should have it's own ZConfig file.
 
-    XXX In the future, the debugger should have it's own ZConfig file.
-  
-  Using the Debugger
 
-    There are several methods you can call on the application object
-    for testing purposes.
+Alternatively, you can also use the ``zopectl`` script to initiate the
+debugger.  It will start up the Zope 3 instance without the servers
+and drop into a regular Python prompt, with the Debugger instance
+bound to the ``debugger`` variable:
 
-    Publish 
+  $ bin/zopectl debug
+>>> debugger
+<zope.app.debug.debug.Debugger object at 0x660350>
 
-      The 'publish' method executes a request as the publisher would
-      and prints the response headers and body::
 
-         >>> debugger.publish(path='/folder/content_object')
+Using the Debugger
+------------------
 
-    Run
+There are several methods you can call on the application object for
+testing purposes.
 
-      The 'run' method executes a request with the publisher's normal 
-      error handling disabled and without outputting anything.  This is
-      useful for use with Python's post-mortem.
+Publish
+~~~~~~~
 
-         >>> debugger.run(path='/folder/content_object')
-         # an exception is raised
-         >>> import pdb; pdb.pm()
-         # enters the python post-mortem debugger
+The ``publish`` method executes a request as the publisher would and
+prints the response headers and body:
 
-    Debug
-      
-      The 'debug' method starts up the publisher in the python
-      debugger, with an extra convenience break point, setup just before
-      the published object call::
+  >>> debugger.publish(path='/folder/content_object')
 
-        >>> debugger.debug(path='/folder/content_object')
-        * Type c<cr> to jump to published object call.
-        pdb> 
-      
-    Arguments
+Run
+~~~
 
-      All of the debugger object's debug methods take optional
-      arguments, the more common/useful ones...
+The ``run`` method executes a request with the publisher's normal
+error handling disabled and without outputting anything.  This is
+useful for use with Python's post-mortem.
 
-      - path - the url path to debug
+  >>> debugger.run(path='/folder/content_object')
+  # an exception is raised
+  >>> import pdb; pdb.pm()
+  # enters the python post-mortem debugger
 
-      - basic - user:password used for HTTP basic auth (it will be
-        base64 encoded by the debug method).
+Debug
+~~~~~      
 
-  Accessing objects (without the debugger)
+The 'debug' method starts up the publisher in the python debugger,
+with an extra convenience break point, setup just before the published
+object call:
 
-    You can use the application object to open a database connection
-    to access your objects.  If the application object is called, it
-    opens a database connection and fetches the root object::
+  >>> debugger.debug(path='/folder/content_object')
+  * Type c<cr> to jump to published object call.
+  pdb> 
 
-       root = debugger.root()
+Arguments: All of the debugger object's debug methods take optional
+arguments, the more common/useful ones...
 
-    For example, to list the objects in the root folder:
+* path - the url path to debug
 
-       print list(root)
+* basic - user:password used for HTTP basic auth (it will be base64
+  encoded by the debug method).
 
-    Also note that, after initializing the application, by creating
-    the root object, you can access any global services setup during
-    initialization. 
+
+Accessing objects (without the debugger)
+----------------------------------------
+
+You can use the application object to open a database connection to
+access your objects.  If the application object is called, it opens a
+database connection and fetches the root object:
+
+  root = debugger.root()
+
+For example, to list the objects in the root folder:
+
+  print list(root)
+
+Also note that, after initializing the application, by creating the
+root object, you can access any global services setup during
+initialization.