[Zope] Difference between Pydoc and DocFinder

[Dieter Maurer]

Damir Bartakovic writes:
 > I really like the idea of pydoc and DocFinder but I am a bit confused. I
 > couldn't find out if it is the same or not. And if not what is the advantage
 > or disadvantage of using pydoc or DocFinder with Zope.
 > I am referring to following sites:
 > http://www.zope.org/Members/shh/DocFinderEverywhere/
 > http://www.handshake.de/~dieter/pyprojects/zope/DocFinder.html
 > http://www.handshake.de/~dieter/pyprojects/zope/pydoc.html

"DocFinder" predates "pydoc". Maybe, I would never have written
"DocFinder" when "pydoc" had already been available.

Both follow the principle:

  Derive accurate documentation directly from the source, not from
  a separate document.

  Both do the same job when classes, methods and their signatures
  are concerned. They use Python's inspection facilities to
  derive the relevant information.

  While "DocFinder" looks for documentation strings, "pydoc" looks
  for documentation comments (preceeding the object).

  "DocFinder", a Zope product, knows about Zope's security
  subsystem and can tell which roles are allowed to use which
  methods. "pydoc", a general purpose Python documentation utility,
  does not know about Zope security.

  "pydoc" is able to directly access an object's source code.
  Thus, you can see all details. "DocFinder" only shows
  class attributes, signature, type, documentation string
  and roles and permissions (currently broken in my Zope
  installation) but not the source code itself.

  "pydoc" has a nice HTTP interface that allows you to browse
  all available sources for documentation. "DocFinder" must be
  called with a Zope object.


"DocFinderEverywhere" allows you to "plug in" "DocFinder" to
(most) objects. They get an additional tab that activates "DocFinder".
Thus, you do not need to call "DocFinder" explicitly.


Dieter