ProductDoc

Amos (10/26)

This document is a work in progress. Please add your comments and I will try to refine the document to address your concerns. BTW, this document will migrate to the Zope Developers Guide when that project gets farther along.

How To Document Your Zope Product

Documenting your Zope Product is important. It lets people know what your product does and how it works. Providing documentation with your product eases your burden since it allows folks to use your product without having to ask you questions. We highly recommend that you include documentation with your Zope product.

README.txt and version.txt

You product can contain two special files:

README.txt

This file is a structured text information file for your product. It is made available via a README tab on your product. It should contain background and introductory information about your product.

version.txt

This is a one line text file that gives the version number of your Product. For example, Foo 1.0.1

In addition to these files you can provide documentation with your product that works with Zope's online help system.

Zope Help System

The Zope Help System provides context-sensitive on-line help for Zope users. The system is flexible and can provide help for Python and ZClass?-based Zope Products.

In the future the Help System will be expanded to provide additional help including API documentation.

Using the Help System

Every standard Zope management screen should include a help button which provides access to help for that screen.

Additionally all the installed help topics can be browsed and searched.

Architecture

All help content is associated with a Product. When a product is installed, its help objects are installed along with it.

Help content is provided by Help Topic objects. These objects live inside Product folders within a special container object called a Product Help object. When you browse a Product folder in the Control Panel you will see these Product Help objects and their Help Topics.

In general you get access to the Help System through an object provided by the Zope Application which has methods for drawing help buttons. This help system object lives in the Zope application object and has an id of HelpSys.

Types of Help

Right now there are three basic types of help that you can offer through the help system:

Management screen help

These help topics give users information about Zope management screens. They explain the purpose and use of a Zope management screen.

API reference

These help topics describe the API of a Zope object for the purpose of DTML and restricted Python Method use. In other words, API references tell Zope users how to script your objects.

DTML reference

These help topics describe DTML tags.

Writing Help for ZClasses?

Suppose you've created an addable type of object with ZClasses?. You'd like the management screens of your objects to have help buttons just like the standard Zope management screens.

First create some Help Topics though the web which document your management screens. Do this by going to your ZClass?'s Product and creating new Help Topics inside the Product Help object.

Next go to your ZClass? and click on the Views management tab. On this screen you define your object's management views. Each view has a name, a method, and optionally a help topic. If you select a help topic for a view, a help button will be drawn on that management view and it will be linked to the help topic you select.

Right now you can not create API reference documentation with ZClasses?. You can create DTML reference topics by naming your Help Topics starting dtml-tagName where tagName is the name of the DTML tag.

Writing Help for Python Products

To support help your Python product needs to register help topics during product registration, and it needs to indicate which help topics should be associated with which management screens.

Registering Help Topics

To register help topics use the registerHelp method on the ProductContext? object. For example:

          def initialize(context):
            ...
            context.registerHelp()

This method will create help topics for all files found in the help subdirectory of the product. Supported file types include: .html, .htm, .txt, .stx, .dtml, .gif, .jpg, .png, .py. Appropriate classes of help topics are used depending on the suffix of the help files.

.html, .htm

Management screen help in HTML format

.dtml

Management screen help in DTML format

.txt, .stx

Management screen help in Structured Text format

.gif, .jpg, .png

Management screen help in graphical format

.py

API reference in Python format. See below for more information on API reference format.

If you want more control over how your help topics are created you can use the registerHelpTopic method that takes an id and a help topic object as arguments. For example:

          from mySpecialHelpTopics import MyTopic

          def initialize(context):
            ...
            context.registerHelpTopic('myTopic', MyTopic())

Associating Help Topics with Management Screens

The chief way to bind a help topic to a management screen is to include information about the help topic in the class's manage_options structure. For example:

          manage_options=(
            {'label':'Edit', 
             'action':'editMethod',
             'help':('productId','topicId')},
            )

In this example, productId refers to the name of the Zope Product in which the class is defined, and topicId refers to the id of the Help Topic associated with this management view.

When Zope draws the management view it will automatically include a help button pointing to the right help topic if you provide this information in the manage_options structure.

Note: sometimes Zope gets confused and defaults to highlighting the first management tab in place of the correct one. To fix this, set the management_view variable to the name of the correct view. If the wrong view is hilighted, then the wrong help button will be drawn.

To draw a help button on a management screen that is not a view, use the HelpButton method of the HelpSys object like so:

          <dtml-var "HelpSys.HelpButton('productId', 'topicId')">

This will draw a help button linked to the specified help topic. If you prefer to draw your own help button you can use the helpURL method instead like so:

          <dtml-var "HelpSys.helpURL(
            topic='productId',
            product='topicId')">

This will give you a URL to the help topic. You can choose to draw whatever sort of button or link you wish.

DTML Reference

If your management screen help topic has an id that begins with dtml- it is assumed to be a DTML reference.

API Reference

API reference help topics describe how to script Zope objects. API reference topics give information about classes. An API reference file is a python file that describes one or more classes using doc strings. Here's an example:

         # comments are ignored
         """
         This is the main doc string for the file. It should briefly
         describe the classes. If there is only one class in the file,
         this doc string is probably not needed.
         """

         def addFoo(id, title):
           """
           Adds a Foo instance to the current object manager
           """

         class Foo::
           """
           This doc string describes the class.

           It should include introductory and background
           information. Doc strings are in structured text format. The
           class doc string should also describe attributes like so.

           Attributes

             title -- The title of the instance.
           """

           # bases are optional, each item in the sequence should be
           # of the form 'Product.APITopic.Class'
           __extends__=('OFSP.Folder.Folder',)

           # optional constructor for addable objects
           __constructor__=addFoo

           def blah(size):
             """
             Describes the method and its arguments. Note that the
             'self' argument is not listed in the method signature.
             """

           def duck(arg1, arg2='default', *arg3, **arg4):
             """
             All standard signature styles are supported.
             """ 

The above API information should be saved in a file, probably named Foo.py in the help directory of your product. When you call context.registerHelp() it will create API reference help topics along with management screen help topics.

The format of an API reference file is quite similar to a normal Python module. It consists of class and function definitions including signatures and doc strings. Doc strings are interpreted at structured text. There are two special class attributes __extends__ and __constructor__ which describe the base classes and the instance constructor function.