[Grok-dev] GrokDocs or: documentation for lazy developers

[Uli Fouquet]

Hi Kevin,

Kevin Teague wrote:
> >
> > Please tell me, what you think!
> >
> 
> Goooooo documentation!

Glad, you say that :-)

> Grok needs docs. More docs, better docs! Having a set of carefully  
> reviewed/core docs is a good idea.

It's meant as a complimentary thing and should in no way substitute the
documentation on grok.zope.org. I've forgotten one point: we had to do
something with the old docs, because there is no more use for the old
website creation tools.

> I like the "Full Screen" layout of the docs. The Table of Contents for  
> the Tutorial is nice too, and the Reference works very well in this  
> format.

That's stolen from the default layout, which looks like this:

  http://docs.python.org/dev/

I only changed some colors and the topics to display in the entry page.

The reference was the main target of that refactoring. It just turned
out later, that sphinx was able to render the complete docs without too
much hassle.

I'd just love to eliminate all excuses for people that change the Grok
API in some way and do not document that in the reference as well. ;-)

> The content could use some tweaking. I would say that evaluation  
> content such as "About Grok" only needs to be on the web site (and  
> probably a few other bits, "Reporting Bugs"? There is an old bits such  
> as the original 'design' notes that should perhaps be moved/archived  
> somewhere?).

Yes, indeed. The 'About Grok' and similar stuff might not be urgently
needed in a local site. I just included it, because it was available and
could be processed so easily. :-) Parts of the texts are stolen from the
default Python docs, as you certainly already noticed. Sometimes I'm too
lazy.

So, for the content-side there is enough work to do. My aim was to have
a tool available, which can process all the docs conveniently. And if
there are no serious objections, we could concentrate on updating the
contents and layout now.

> The Reference needs more content and polish! I'm willing to do some  
> work on filling this out some more (as well as do some CSS tweaking),  
> should I commit to the 'ulif-grokdocs' branch?

Yes, yes, yes. That would really be great! Please go ahead! You can find
the CSS stuff in `doc/.static/grok.css` (the '.static' is a sphinx
builtin-setting; sphinx looks in that directory and copies it to the
target directory).

The default index template is the doc/build/docindex.template. Other
templates can be found in `doc/build/sphinx/templates` (but cannot be
changed in that location; it's an svn:external).

Concerning the structure of doc/: I tried to put all build-specific
stuff like templates, scripts, etc. into `build/`, so that people are
not too confused when they have a look into this directory. The conf.py
is needed by sphinx in that location.

There is also some finetuning of the output needed. Sidebars for example
are rendered strange or not at all in HTML (see the tutorial) and some
lines are rendered crappy in LaTeX/PDF. But that needs (monkey-)patching
of the sphinx engine. Luckily, Georg Brandl is very helpful and
responsive in that respect, so that we can tell him our wishes and
complaints, before the first cheeseshop release of sphinx will be done.

Please ask, if there are any questions!

Best regards,

-- 
Uli