DocFinder 1.0.3

1 Introduction

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:

  1. for product programmers
  2. for script/DTML programmers
  3. for through the Web users

2 Function

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.

2.1 Instantiation

DocFinder is instantiated in the normal way (via the add list). For backward compatibility, you should use the id showDocumentation. We assume this below.

2.2 Documenting an object

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:

  1. calling is via an URL
     URL_to_OBJECT/showDocumentation
       
    
    will present the documentation for OBJECT.
  2. calling it from DTML with implicit argument passing
     <dmtl-var showDocumentation>
       
    
    will present the documentation for this().
  3. calling it from DTML with explicit argument passing
     <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

2.3 Documentation options

You can pass additional parameters either via the request object, the DTML namespace or as explicit keyword arguments. Recognized parameters are:

ObjToDoc__
the object to be documented. It can also be provided as first positional argument.
DocType__
Type of the documentation. This can be either scripter (default), web or programmer for documentation targeted to script, web or product authors.
DocMethodRe__
a regular expression that specifies the methods which should be documented. If it is empty (the default), all methods are documented. Otherwise the methods matched by the regular expression are documented; this implies that a normal string (without any regular expression special characters) will show methods the name of which begin with this string and a regular expression of the form .*string shows methods with string in their name.

2.4 Code access

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.

2.5 Customization

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.

2.6 Security

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
instance creation
DocFinder: document object
protects __call__ and analyseDocumentation
DocFinder: show code
protects getCodeFor and showCodeFor

Initially, only Manager has these permissions.

3 What's new

3.1 Version 1.0.3

Do not use docstring for primitive types.

3.2 New in version 1.0.2

3.3 New in version 1.0.1

3.4 New in version 1.0

4 Download

Download DocFinder 1.0.3 as a 11 kB TGZ archive.

5 Installation

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.

6 Known problems

7 License

DocFinder is distributed under an BSD like open source license. Please see the copyright notice of DocFinder.py for details.

8 Requirements

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.