[Grok-dev] finishing reference docs

[Kevin Teague]

> Could anyone outline the missing and incomplete parts at
> http://svn.zope.org/grok/trunk/doc/reference
> to get the docs more complete for the next release?
>

Right, I almost got those docs good enough for release and then ... I  
took a week long trip to Bermuda and the cruise ship I was on went  
through the Bermuda Triangle and disappeared for several months.

(ok, no, I'm just too easily distracted ...)

There only a few small things to do, such as tidy up the reference  
index page a bit (remove that model.rst reference for example, and  
that link to the PDF - or make PDF generation work, I never got that  
done). There might be one or two XXX sections, and there are still  
quite a few places where the docs are empty or quite thin, but "thin"  
docs are better than no docs, so I wouldn't let that hold up  
completion of the work.

There are larger, more ambitious things to tackle post 0.14, such as  
extending Sphinx to have an Interface keyword so that the distinction  
can be better made between interfaces and classes in the docs. It  
might also make sense to push some of the doc changes back into Grok,  
and then have Sphinx extract those docs from the code artifacts in the  
grok source. I think it'd also be nice to aim for a larger, richer set  
of reference docs over time - Sphinx is quite at making menus and such  
so that it's easy enough to find the relevant section you are looking  
for, but it's annoying when the docs in that section are quite thin  
and really meaty explanation and example would be much more welcome.

Not having done any web work for a few months, I did start back up on  
some Grok work this week - I have been finding the reference docs  
quite useful as a refresher!

(and hopefully I'll get off my lazy ol' ass and start doing some more  
doc contributions in the not too distant future - but of course please  
don't let that deter you from working on the docs!)