API doctool Generator

Status

Author

Problem

Several people have indicated to me that they would like to have the API docs that come with Zope 3 available, even if Zope 3 itself cannot start up. This mainly addresses the use case that you want to look up documentation when you did something wrong.

Goals

Implement the tools to build a static version of the API docs.

Proposed Solution

We discussed several approaches on IRC with several people. The easiest solution we could come up with would be the usage of wget to retrieve the documentaion from a running Zope 3 server.

I did some testing and wget seems to work well for what we need. There are only a few (simple) issues that have to be addressed:

wget does not handle unconventional/new URLs? correctly:

        <style type="text/css" media="all"> 
          @import url(http://localhost:8080/@@/apidoc.css);
        </style>

This means we need to employ more conventional schemes for those cases. I would really like to avoid file-postprocessing.

wget creates a useless localhost:8080 and ++apidoc++ directories. This could be addressed my some simple filesystem commands.
We cannot use the search facilities as they are available by default in the menus. A simple solution to the problem would be to show all entries by default and implement a simple filter in Javascript.
Most of the time on my initial trial was spent getting all possible combinations for the static tree. The solution would be to develop a JS-based tree.

Out of Scope (for this proposal)

A utility that generates other documentation formats, such as PDF, LaTeX?, docbook, etc.
A utility that further compiles the documentation to other help formats, such as CHM.

Risks

wget does not exist by default on all platforms, so the generator cannot be run there. However, I don't think that this justifies abandoning the simplicity of this approach or not use this very powerful tool.

comments:

Final Implementation --srichter, 2005/10/31 10:54 EST reply
It turned out that wget had some other issues that could not be addressed. A custom tool was written that is much more specific, but provides the flexibility we need. It is also able to use the publisher directly instead of using a Web server.

Other than that the approach outlines here was chosen.