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 ------------------------------------------------------