AW: [Zope] Difference between Pydoc and DocFinder

[Damir Bartakovic]

Ok, thanks for your precise description. I think I understand it, almost ...
Since I am new to Python, just a little thing.
>  While "DocFinder" looks for documentation strings, "pydoc" looks
>  for documentation comments (preceeding the object).

With documentation string you ment the __doc__ attribute ?
So it is doing the same thing like HappyDoc
(http://happydoc.sourceforge.net/)?
Like I saw Happydoc is also used to for the Zope Documentation
http://www.zope.org/Documentation/Developer/ZopeSrcDocs

And a documentation comment looks like """ this is a comment """ or?

cheers
Damir

-----Ursprungliche Nachricht-----
Von: Dieter Maurer [mailto:dieter@handshake.de]
Gesendet: jeudi 22 novembre 2001 19:45
An: Damir Bartakovic
Cc: zope@zope.org
Betreff: Re: [Zope] Difference between Pydoc and DocFinder


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