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

[Uli Fouquet]

Jan-Wijbrand Kolman wrote:
> On 1/5/11 15:15 PM, Uli Fouquet wrote:

[snip: my lengthy reply]

> 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.

Excellent!

> * 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.

Yep, fully agreed.

> * 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.

Basically, we can publish API docs for packages on packages.pypi.org and
enable the intersphinx feature with Sphinx. That would out-of-the-box
enable references like

  :mod:`grokcore.view`

in arbitrary other docs (for example in groktoolkit docs). So we could
easily link docs from different packages together.

For referencing more 'descriptive' or prosaic parts of other docs
(contrary to pure code-describing stuff), say a certain 'chapter' of
grokcore.component docs, this wouldn't help. But maybe sphinx has even
some helper for that case and if we stick with the 'API-specific stuff
into package docs, larger stories and tales into groktoolkit docs' it
might even be unneeded.

We _could_ also publish the docs of packages on grok.zope.org and make
intersphinx look it up. But I guess it is much easier to only publish
the explicit groktoolkit docs (and maybe the grok-API aka reference) and
let it link to packages.python.org which can be updated when a new
release of a package was made.

The only problem I can see here is that PyPI supports docs only for one
version of a package. One could lose docs of older releases then when
updating the docs.

> 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?

Absolutely, thanks for bringing my thoughts into less words! 

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/1d56ba18/attachment.bin