[py-svn] r36267 - py/dist/py/documentation

[hpk at codespeak.net]

Author: hpk
Date: Mon Jan  8 14:43:00 2007
New Revision: 36267

Modified:
   py/dist/py/documentation/apigen.txt
Log:
a bit of rewriting the apigen introduction ... 
the real thing is to consider all apigen docs
and sort/merge them. 



Modified: py/dist/py/documentation/apigen.txt
==============================================================================
--- py/dist/py/documentation/apigen.txt	(original)
+++ py/dist/py/documentation/apigen.txt	Mon Jan  8 14:43:00 2007
@@ -5,18 +5,27 @@
 ------------
 
 Apigen is a tool for automatically generating API reference documentation for
-Python projects. It distinguishes itself from comparable tools by examining
-code at runtime, rather than at compile time. This way it is capable of
-displaying more information about registered and discovered classes and
-functions (although it may find less of them). The tool can either be used
-from code, or from py.test, in the latter case it will gather information
-about modules registered using `initpkg`_.
+Python projects.  It works by examining code at runtime rather than at 
+compile time.  This way it is capable of displaying information 
+about the code base after initialization.  A drawback is that
+you cannot easily document source code that automatically
+starts server processes upon getting imported. 
+
+The apigen functionality can either be used from code, or from
+py.test, in the latter case it will gather information about
+modules and names exported explicitely via the `initpkg`_ mechanism. 
+
+Please note that apigen is currently geared towards documenting the
+py library itself, making it nicely work for other projects
+may still require a bit of adaption and refinement work. 
 
 Using from code
 ----------------
 
+XXX how to use it without any Tracer? 
+
 The library provides a simple API to generate a py.rest.rst tree (which
-can be converted to ReStructuredText), along with some helper classes to 
+represents a ReStructuredText document), along with some helper classes to 
 control the output. The most important objects are the Tracer, which traces
 code execution by registering itself with sys.settrace, the DocStorage class,
 that stores Tracer information, and the RestGen class which creates a ReST