[Grok-dev] Re: grok reference - yet another test URL
faassen at startifact.com
Thu May 31 11:55:20 EDT 2007
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
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. :)
More information about the Grok-dev