Hallo all, 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 thanks Damir
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
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
Damir Bartakovic writes:
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 ? Yes. .... And a documentation comment looks like """ this is a comment """ or? That a documentation string (going into __doc__), if it is the first statement in an object (module, class or function).
A documentation comment is a comment (a block of lines starting with '#') usually preceeding an object. Dieter
participants (2)
-
Damir Bartakovic -
Dieter Maurer