[Grok-dev] Re: grok reference - yet another test URL

[Martijn Faassen]

Hi there,

My opinions on an auto-generation tool:

An auto-generation tool can help bootstrap the process and helps us make 
sure we have complete docstrings where necessary. It could also help if 
we need to update the reference by pointing out which areas have changed 
in the docstrings.

I do consider it important that we don't lose track of ourselves with 
cool tools. I think we should hand-write most of the reference. 
Docstrings and automatic generation of documentation can get us only so 
far. The reference is more than just the documentation of methods and 
functions, and needs to be a coherent document by itself. That is 
easiest to accomplish by sitting down and considering it as a document. 
We need examples and references other information, for instance.

I wonder how the Python core documentation processs does it (we're 
inheriting the toolset from them). Do they have tools to extract 
docstrings as well, or are the docstrings maintained separately from the 
reference itself? It would be interesting to find out.

Uli, concerning auto-generation of documentation, I think it has its 
place by exposing the massive amounts of interfaces and doctest 
information already in the Zope 3 core (and the little bit in Grok, of 
course).

We need to investigate what zope 3's apidoc does and how it works. Can 
we reuse code? Does it have gaps we need to fill?

What I'd like to see is something that's really very easily available in 
the grok admin interface. No "you need to turn on apidoc mode before you 
see it show up". No documentation all bunched up in a separate popup 
window. Instead, links integrated in the admin UI that show up whenever 
it detects you're using a particular interface, or using a particular 
package. I don't quite know what this should look like. It should just 
be so easy to use that people find it more easy in many cases than just 
going through the Zope 3 source code. Though of course references to 
source code so it's easy to start grepping that would also be useful. :)

Regards,

Martijn