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

[Jan-Wijbrand Kolman]

On 1/5/11 15:15 PM, Uli Fouquet wrote:
>> 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'.

My ideas at this point (thanks for the detailed reply!):

* Yes, we should use the autodoc feature for generating documentation 
from the docstrings. We certainly should avoid duplication of API 
documentation.

* We could start generating these autodocs for all grok* packages, so 
that each of the packages have up to date (and hopefully at some point 
also *complete*) API documentation.

* The tutorial-like and overview-like documentation would still neatly 
fit in the groktookit package. And we should explore how we can 
"dynamically" integrate the autodoc-generated documentation from the 
individual packages into this groktoolkit documentation tree.

I think we then would have best of both worlds: the API documentation is 
within the individual package, were it belongs. And the more general 
documentation is in groktoolkit, however when building the documentation 
everything is aggregated in one tree when published online.

Does this make sense to you?

regards, jw