Log in
Forgot your password?
History for ProductDoc
??changed:- 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, [53 more lines...]