[Zope-dev] "pydoc" for Zope - another great documentation finding tool

[Dieter Maurer]

I installed Python 2.1 and checked what great new things are there:
they are numerous!


As you know, I am a fan of documentation - reliable documentation,
if possible directly extracted from the source.
Therefore, the new Python documenter "pydoc" was very attractive for me.


I had to tweak "Zope" and "pydoc" a bit such that they work nicely
together:

  *  "pydoc" imports the modules to find out about its content.
     Zope does not like to be imported, when another Zope
     process is running.

     Solved by calling "FileStorage.FileStorage" with the
     "read_only" parameter in "Zope.__init__", if instructed
     by an environment variable

  *  "pydoc" is slightly confused by some of Zope's extension
     classes: it wants any class to have a "__module__"
     attribute. Zope's extension classes do not have it.

     Solved by wrapping pydoc's "__module__" access in an
     "try .... except".

  *  "inspect" does not understand "Python Methods" (and
     other Zope methods). Correspondingly, Zope class documentation
     was almost empty.

     Solved by defining "implementsMethodInterface" and
     replacing "inspect.ismethod" by this function (at runtime).


After these tweaks, "pydoc" can document Zope code.
It is a bit overwhelming:

   The "pydoc" authors decided to document inherited methods with the
   class itself. As a consequence, for each Zope class, hundreds of
   mostly irrelevant methods are documented.

   But it should be easy to change this to get something
   similar to "javadoc": summary information for inherited methods.

Already in the current state, I think, it is a great help
for Zope developpers.


If there is interest, I can post my changes.



Dieter