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

[Jan-Wijbrand Kolman]

On 1/8/11 13:54 PM, Vincent Fretin wrote:
> On Wed, Jan 5, 2011 at 4:15 PM, Uli Fouquet <uli at gnufix.de
> <mailto:uli at gnufix.de>> wrote:
>
>     Basically, we can publish API docs for packages on packages.pypi.org
>     <http://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
>     <http://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 <http://packages.python.org>
>     which can be updated when a new
>     release of a package was made.
>
> You can use an anchor in grokcore.component docs:
> .. _mychapter:
>
> and you can use the intersphinx feature like this:
> :ref:`My chapter <mychapter>`
> or explicitly say which sphinx you want to link:
> :ref:`My chapter <grokcore.component:mychapter>`

Thanks for the suggestions! We need to experiment with this.
regards, jw