[Grok-dev] grok documentation, again

[Jan-Wijbrand Kolman]

hi,

Last weeks I have been on and off working on rearranging Grok's 
documentation. It has moved from the grok package to the groktoolkit. I 
tried to simplify the documentation-generation and for the recent 
releases *and* for the development version, the documentation on the 
grok.zope.org website is generated from this:

   http://grok.zope.org/doc/current/
   http://grok.zope.org/doc/1.3.2/
   http://grok.zope.org/doc/dev/  <-- build every hour from the trunk

The community documentation is build every hour on this URL:

   http://grok.zope.org/doc/community/

For the groktoolkit trunk I started rearranging the documentation 
structure. Most importantly, the packages document..:

   http://grok.zope.org/doc/dev/packages.html

..is automatically generated during the documentation build process. 
Furthermore I added a releases document here:

   http://grok.zope.org/doc/dev/releases.html

It is my intention to replace the current "releases" page in Plone with 
this one as it is much easier to update this document when making a release.

Originally we had a link to a the change log too in this documentation 
tree. Since the groktoolkit has no change log *and* the change log of 
just the grok package is by for not enough, I removed it. I'd like to 
generate a change log page for all of the groktoolkit packages somehow 
as it is important information.

While working on all of this, I realized this:

We have *a lot* of documentation lying around. We really do!

But its organization is far from optimal by now *and* most of the 
documents need a round of updates. In other words, if we - as grok 
community - do care for good documentation, we need to again put some 
effort in it.

Some of the todo items I see now:

* Start adding descriptive docstrings to all the components in the 
grokcore.* family and related packages. If we do that the "sphinx-way" 
we can generate package documentation very neatly.

* There are some packages (like grokcore.component) that have a fairly 
elaborate README.txt. While this is good(!), we need to somehow 
consolidate this worthwhile information into one easily found place.

* Update the tutorial. The tutorial needs to be tested against recent 
Grok release.

* Update the reference. The reference document contains lots of useful 
information. Some of this information might actually belong in the 
individual packages perhaps. Sphinx has tools to aggregate this 
information into one nice document.

* Finish the transition from Plone to the sphinx based community 
documentation.

* Consider what documents from the community docs might be better places 
in the "official" tree.


All of this will take A Fair Amount of Organization and Hard Work.

If you find yourself with an hour to spare and want to help out with 
this, please coordinate on IRC and/or on the list with us. You can ask 
me for questions regarding building the documentation tree, and perhaps 
about the organization of the documents. You can also talk to me about 
how to integrate the various documentation trees into one.

regards, jw