[Grok-dev] [Grok-doc] heads-up: moving grok's official documentation to the groktoolkit

[Uli Fouquet]

Hi JW,

(this reply goes to grok-dev only to avoid crossposts)

Jan-Wijbrand Kolman wrote:

> (sorry for the crosspost - did we conclude we can merge the doc 
> mailinglist with the grok-dev list, or not yet?)

Don't know, but I wouldn't oppose to merge.

> This is a Heads-Up that I'm about to move the doc subdirectory of 
> grok-the-package to the groktoolkit. There we can maintain the official 
> documentation for Grok.
> 
> After the move it will be (I hope) easier to both maintain the Grok 
> documentation and write tools/scripts to update the website, and to make 
> releases of grok-the-package.
> 
> If I didn't get a "please hold on a moment" response by, say, 17:00 UTC, 
> I'll indeed go ahead and do the move.

Okay, this is a "please consider a hold" for now ;)

Frankly, I cannot see the immediate advantage of this move. I still like
the 'one-package-one-documentation' approach which means: docs can go to
packages.python.org/<pkgname> (and maybe other places like grok.zope.org
too). But groktoolkit is not planned to be 'released' in the PyPI-sense,
right?

Then, we still have special API pieces in grok (the package) which IMHO
shouldn't be mixed up with groktoolkit.

If groktoolkit then is planned as the-one-and-only documentation place
for core groktoolkit packages like grokcore.view, grokcore.component,
etc., this might make things more difficult in case we use autodoc.

I started to switch the reference docs from descriptions-in-the-docs to
docstring-descriptions deployed by Sphinx autodoc feature. This revealed
that not only lots of description where given two times (one time in the
rst-Files, one time in the code; hard to maintain) but also descriptions
of class-,  method-, and function-signatures were simply outdated or
didn't exist anymore. Using autodocs we can be a bit more confident that
doc descriptions really match the source code. In other words: I'd
really love to see us using Sphinx autodoc as much as possible.

This wouldn't be that easy if we put all 'grok-related' docs into
groktoolkit.

Overall we should decide, whether we want descriptions of APIs going
with the respective package (then at least the reference docs should
stay in grok-the-package) or not. I'd really prefer the former over the
latter.

It's different with the developer notes and the tutorial. These docs
might not be strictly bound to grok-the-package. So, overall, I'd opt
for moving _some_ docs to groktoolkit but the reference might stay in
the old place until grok-the-package is really nothing more than a
collection of imports from other packages (even then correct reference
docs would make sense to me) or stops to exist at all.

Building the grok-documentation, by the way, is now done like with many
other Python packages: run `sphinx-build` with the appropriate
arguments. There is no special stuff to be injected in the build-stuff
any more, I removed all that. The build-scripts on the server might want
to reflect this.

I understand that having groktoolkit docs would not be bad, but maybe
they should really be written from scratch and not copied over
completely from grok. IMO they should tell about groktoolkit, how it
relates to grok-the-package, maybe grokproject and similar things more,
much like what the ZTK docs do for the ZTK. But the groktoolkit docs
should IMO not replace any reference docs. Docs for packages like
grokcore.component, etc. should instead go into the respective packages.
At least leaving grok-the-package without own docs is a bad idea IMHO.

Moving the build scripts for the server, however, makes sense to me.

Sorry for being confusing! This is not a strict 'dont-do-it' but a
friendly 'please-reconsider-and-maybe-split-the-move'.

Best regards,

-- 
Uli

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://mail.zope.org/pipermail/grok-dev/attachments/20110105/a8b98088/attachment.bin