[Zope] Auto-Documenting Zope Products

[Terry Hancock]

Hi Dieter,   (CC'd Zope list)

I only just discovered the pydoc module in Python 2.1
and was trying it out on my Zope product (I was previously
using "HappyDoc", which was unfortunately not finding
everything I wanted it to -- presumeably because some
things are added dynamically).

Anyway, I noticed that you have a set of pydoc/zope
patches for improved functionality.  Neat.

http://www.dieter.handshake.de/pyprojects/zope/pydoc.html

I'm writing because I noticed some interesting things while
playing with the inspect module (which pydoc uses).

You've already got a patch to make pydoc recognize
Python Methods, but I noticed that DTMLFile() and
SQL() objects show up as python methods when I examine
their type. So far the best way I've found to identify
them is to look at their docstrings, which are
inherited from the original DTMLFile/HTMLFile class
and the SQL class respectively.  It seems to me that
it is a useful thing to be able to recognize whether
a method is Python, DTML, ZSQL, ZPT, or whatever --
especially since they are usually used for different
things.

So far, I've noticed that:

  DTMLFile objects' docstrings begin with "HTMLFile"
  ZSQL objects' docstrings begin with "SQL"

It seems likely that the others could be identified this
way too. Or is there a smarter way to do it?  I'm a
little concerned that the docstrings might change in
different Zope versions.

I'm unsure what to do about this, but I was wondering
if there might be some useful way I could contribute
detection code to your pydoc patches?

Also it seems like pydoc might be best invoked from
within Zope, though I've been trying to do it from
the interpreter with, e.g.:

>>> import Zope
  Actually this generates a traceback, because the ZODB
  is supposed to be locked by my running Zope instance,
  but it seems to work anyway for my purposes.

>>> import Products.myproduct
>>> import pydoc
  ...

Unfortunately, I haven't figured out how to
generate a full documentation set for the product
this way -- I've managed to generate individual
HTML pages, but I don't seem to be doing it right
yet.

I also incorporated a useful trick for documenting
complex DTML pages, which I use in my Narya product:

http://www.anansispaceworks.com/Narya/Forum?debuglayout=1

which is basically to wrap DTML objects in a table with
a label derived from the document_id.  I'm not sure if
there's a more automatic way to do it.  But the point
is that if DTML is supposed to be for doing visual layouts,
it seemed logical to document it visually as well --
let the layout show you how the templates are used
together.  I'd like to figure out a way to do this so
it doesn't depend on the page design to do it, but this
isn't too demanding (I just have to include a small DTML
method call in the headers and footers).

Cheers,
Terry

-- 
------------------------------------------------------
Terry Hancock
hancock@anansispaceworks.com       
Anansi Spaceworks                 
http://www.anansispaceworks.com 
------------------------------------------------------