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

[fijal at codespeak.net]

Author: fijal
Date: Tue Jan  9 17:11:39 2007
New Revision: 36373

Modified:
   py/dist/py/documentation/apigen.txt
Log:
written down a bit of refined interface.


Modified: py/dist/py/documentation/apigen.txt
==============================================================================
--- py/dist/py/documentation/apigen.txt	(original)
+++ py/dist/py/documentation/apigen.txt	Tue Jan  9 17:11:39 2007
@@ -9,11 +9,11 @@
 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. 
+starts server processes or has some other irreversible effects 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. 
+modules, classes to export explicitely by using provided script. 
 
 Please note that apigen is currently geared towards documenting the
 py library itself, making it nicely work for other projects
@@ -22,8 +22,6 @@
 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
 represents a ReStructuredText document), along with some helper classes to 
 control the output. The most important objects are the Tracer, which traces
@@ -100,20 +98,18 @@
 Using from py.test
 -------------------
 
-XXX: fijal, please help me here a bit ;)
-
 Running unit tests forms an ideal opportunity for apigen to find out about what
 happens when code is executed (assuming you have proper test coverage ;). There
-are hooks built into py.test that allow you to do that: just write a simple
-class called 'ApiGen' in your conftest (see the `py.test documentation`_ for
-more details about conftest files) that implements a set of special methods
-called 'get_doc_storage()' and 'write_docs()', that essentially implement the
-functionality discussed above. Calling py.test with an --apigen
-argument will cause the methods to be called.
-
-For an example, see the 'conftest.py' file in the py lib itself. To see it in
-action you run `py.test --apigen` in the root of the py lib; this
-will result in documentation (in HTML) being written to /tmp/output.
+are hooks built into py.test that allow you to do that:
+
+* Write down a python script which contains at least two functions
+  - `get_documentable_items() -> {}` - function which will return dictionary
+    of name to object of exported items
+  - `build(pkgpath, docstorageaccessor)` - function which will be invoked afterwards
+    with DocStorageAccessor instance as an argument (you should read DocStorageAccessor
+    interface to know how you can access it)
+
+XXX: Write down some example usage after guido implement the script
 
 Comparison with other documentation generation tools
 ----------------------------------------------------