It is often difficult to find accurate documentation about the
Zope infrastructure. Often, I have written: look into the Zope
source, its source documentation is quite good. However, as Zope's
implementation language Python provides good introspection
facilities, there is a better way: extract the documentation
directly from Zope. That's what DocFinder
does. It
analyses any Zope object inside a running Zope, determines which
classes have been used in the object's makeup and provides
information about their class level attributes: name, allowed
roles, arguments, documentation strings. It provides (read only)
access to to source code of Python implemented classes and
methods.
This information can help you in various ways:
The product provides only information about class level attributes, because there are almost surely too many instance attributes, you may not be interested in. You will get, however, information about the access permissions for instance attributes, if they do not provide their own permissions. This affects mostly properties.
The product supports three kinds of documentation:
DocFinder
is a small product that allows to ask
Zope for documentation about its objects.
Unlike the API documentation which describes how thing should be, the DocFinder documentation describes (at least partially) how they really are: complete and accurate. The information contains documentation strings. This information is, of course, also unreliable. What is reliable are the available methods, their parameters and their security information.
DocFinder
is instantiated in the normal way (via
the add
list). For backward compatibility, you should
use the id showDocumentation
. We assume this
below.
To show documentation for an object, you will call
showDocumentation
for this object. It will present the
documentation as a two level explorable tree structure. The first
level describes the classes from which the object is built. The
second level provides information about its attributes. Classes and
method attributes are links to their source code.
For each class level attribute, its name, the roles allowed to access the attribute, its arguments (if any), the documentation (if any) or its type and a comment (for methods, if the comment preceeds the method definition) are shown.
Calling showDocumentation
on an object can take
three forms:
URL_to_OBJECT/showDocumentationwill present the documentation for OBJECT.
<dmtl-var showDocumentation>will present the documentation for
this()
.<dmtl-var "showDocumentation(_.None,_,ObjToDoc__=object)">will present the documentation for object.
Some objects intercept traversal (e.g. Python Scripts and Page
Templates). You cannot call for documentation for these objects
with the URL form above (as the trailing
showDocumentation
is intercepted and not called). To
support documentation for these object,
showDocumentation
has an attribute
document
(a Python Script) that can be used in the
following URL form:
URL-To-showDocument/document/Path-To-Object?
optional-arguments
You can pass additional parameters either via the request object, the DTML namespace or as explicit keyword arguments. Recognized parameters are:
ObjToDoc__
DocType__
scripter
(default), web
or
programmer
for documentation targeted to script, web
or product authors.DocMethodRe__
.*string
shows methods with
string in their name.showDocumentation
provides the methods
showCodeFor(classOrMethod)
and
getCodeFor(classOrMethod)
for direct code
access documented classes and methods implemented in Python. It
uses Python's inspect
module for this.
getCode
returns filename, start and end line number
and the module source. showCodeFor
calls the
PageTemplate showCode
with callOrMethod as
codeFor
and this code info as codeInfo
parameters. You can customize showCode
as needed.
showDocumentation
uses
analyseDocumentation
as an auxiliary do analyse the
object for documentation. The result is a Doc
instance. It behaves like a sequence of ClassDoc
instances and the method tpValues
returns such a
sequence. It supports the parameterless methods
ObjToDoc__
, DocType__
,
DocMethodRe__
, Path
and
Title
.
Each ClassDoc
provides methods Name
,
Doc
, Module
, Comment
,
FullName
. Furthermore, it behaves like a sequence of
AttributeDoc
instances and tpValues
returns such a sequence.
Each AttributeDoc
provides methods
Name
, Permission
, Roles
,
Args
, Doc
, Type
,
Comment
, DocOrType
and
FullName
.
showDocumentation
calls the Page Template
showTree
with a Doc
instance as
DocInfo
parameter. You can modify
showTree
to customize the documentation
presentation.
DocFinder
reveals deep information about Zope and
your application (it provides read access to all sources!). You may
consider this a privacy and security risk. Install
DocFinder
only in trusted installations (e.g. your
development system behind a firewall). Do not install it in
installations with unprotected internet access.
DocFinder
operations are protected by the
permissions:
DocFinder: add instance
DocFinder: document object
__call__
and
analyseDocumentation
DocFinder: show code
getCodeFor
and
showCodeFor
Initially, only Manager
has these permissions.
Do not use docstring for primitive types.
string.translate
of Python 2.1.3 --
does not like empty argument).DocFinder
instance (rather than a DTML object and External Method pair)Download DocFinder 1.0.3
as a 11 kB TGZ archive.
Untar the archive in your Products directory. This will create the directory DocFinder.
Restart your Zope. You should now find a DocFinder
entry in your add list. Instante DocFinder
in the
normal way. Use the default showDocumentation
as
Id.
You may want to install Stefan H. Holek's DocFinderEverywhere.
It uses (so called) monkey patching, to give most Zope objects a
"Doc" tab that displays the DocFinder
information.
Unauthorized
exception..../showDocumentation/document/name
...
will fail, whenever name happens to be
an addribute of document
. In this case,
document
will not intercept the traversal and the
complete URL will be traversed by ZPublisher. This may lead to
incomprehensible error messages. This is a general problem of
traversal interception by Python Scripts (such as
document
).DocFinder is distributed under an BSD like open source license. Please see the copyright notice of DocFinder.py for details.
DocFinder
was developed for Zope 2.6. It will not
work for Zope versions before 2.3. It requires Python 2.1.3 or
above.