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

[guido at codespeak.net]

Author: guido
Date: Thu Nov 16 14:32:28 2006
New Revision: 34667

Added:
   py/dist/py/documentation/apigen.txt
Log:
Document describing the current implementation of apigen (fijal, please
review!), needs to be merged with the older documents describing ideas in
apigen/ at some point, for now however it provides a basic explanation of
wat apigen is and how to use it.


Added: py/dist/py/documentation/apigen.txt
==============================================================================
--- (empty file)
+++ py/dist/py/documentation/apigen.txt	Thu Nov 16 14:32:28 2006
@@ -0,0 +1,117 @@
+apigen - API documentation generation tool
+===========================================
+
+What is it?
+------------
+
+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`_.
+
+Using from code
+----------------
+
+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 
+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
+tree (see py.rest.rst).
+
+Gathering information
+++++++++++++++++++++++
+
+To gather information about documentation, you will first need to tell the tool
+what objects it should investigate. Only information for registered objects
+will be stored. An example::
+
+  >>> import py
+  >>> from py.__.apigen.tracer.docstorage import DocStorage
+  >>> from py.__.apigen.tracer.tracer import Tracer
+  >>> toregister = {'py.path.local': py.path.local,
+  ...               'py.path.svnwc': py.path.svnwc}
+  >>> ds = DocStorage().from_dict(toregister)
+  >>> t = Tracer(ds)
+  >>> t.start_tracing()
+  >>> p = py.path.local('.')
+  >>> p.check(dir=True)
+  True
+  >>> t.end_tracing()
+
+Now the 'ds' variable should contain all kinds of information about both the
+py.path.local and the py.path.svnwc class (it will walk through 'toregister' to
+find information about all it contains), and things like call stacks, and
+possible argument types, etc. as additional information about
+py.path.local.check() (since it was called from the traced code).
+
+Viewing information
+++++++++++++++++++++
+
+Viewing the information stored in the DocStorage instance isn't very hard
+either. As explained there is a RestGen class that creates a py.rest.rst tree,
+which can directly be serialized to ReStructuredText, which can in turn be
+converted to other formats. Also the py.rest.rst tree can be manipulated
+directly, or converted to formats other than ReST (currently only HTML) using
+special transformers.
+
+There are several helper classes available that wrap the output format 
+generation. There are two types of helper classes, 'LinkWriters' and 'Writers'.
+The first are responsible for generating external links (for viewing source),
+the second for generating the actual output from the py.rest.rst tree, and
+for generating internal links (which is directly related to generating output).
+Instances of these classes are passed to the RestGen class as arguments on
+instantiation.
+
+An example of creating a directory with seperate ReST files (using DirWriter)
+from the 'ds' DocumentStorage instance we created below, without any external
+links (using DirectPaste).
+::
+
+  >>> from py.__.apigen.rest.genrest import RestGen, DirectPaste, DirWriter
+  >>> # create a temp dir in /tmp/pytest-<userid>
+  >>> tempdir = py.test.ensuretemp('apigen_example')
+  >>> rg = RestGen(ds, DirectPaste(), DirWriter(tempdir))
+  >>> rg.write()
+
+An example of a somewhat more 'real-life' use case, writing to a directory of
+HTML files (this uses py.rest.transform), generating links to ViewVC source
+views::
+
+  >>> from py.__.apigen.rest.genrest import ViewVC, HTMLDirWriter
+  >>> from py.__.apigen.rest.htmlhandlers import HTMLHandler
+  >>> tempdir = py.test.ensuretemp('apigen_example_2')
+  >>> rg = RestGen(ds, ViewVC('http://some.host.com/viewvc/myproj/trunk/'),
+  ...              HTMLDirWriter(HTMLHandler, HTMLHandler, tempdir))
+  >>> rg.write()
+
+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 (only works
+when --session is used) 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 --session=L --apigen` in the root of the py lib; this
+will result in documentation (in HTML) being written to /tmp/output.
+
+Questions, remarks, etc.
+-------------------------
+
+For more information, questions, remarks, etc. see http://codespeak.net/py.
+This website also contains links to mailing list and IRC channel.
+
+.. _`initpkg`: http://codespeak.net/svn/py/dist/py/initpkg.py
+.. _`py.test documentation`: http://codespeak.net/svn/py/dist/py/documentation/test.txt
+