[Grok-dev] Linking to the Grok Documentation

[Uli Fouquet]

Hi there,

Sylvain Viollon wrote:
> On Thu, 25 Nov 2010 19:18:37 +0100
> Sebastian Ware <sebastian at urbantalk.se> wrote:
> 

[snip: sphinx.ext.intersphinx]

> >   intersphinx_mapping = {
> >       'grok': ('http://grok.zope.org/doc/1.2.1', None),
> >       }
> > 
> > Find links that can be refered to:
> > 
> >  http://grok.zope.org/doc/1.2.1/objects.inv
> > 
> > By using the following markup:
> > 
> >  :py:class:`Hello <grok.LocalUtility>`
> > """
> > 
> 
>   That sound interesting, I will test it.

Yep, it's pretty useful. You can add links to current Python standard
lib docs like this::

  intersphinx_mapping = {
        'python': ('http://docs.python.org/', None),
      }

or like this, if you prefer to reference a certain version of Python::

  intersphinx_mapping = {
        # reference Python 2.6 docs...
        'python26blah': ('http://docs.python.org/release/2.6.6/', None),
        # reference also grok...
        'grok': ('http://grok.zope.org/doc/1.2.1', None),
        # add more external docs here...
      }

and some ReST construct like::

  The :class:`grok.LocalUtility` does not 
  accept :class:`StringIO.StringIO` instances.

should then automatically link to the appropriate docs. Generally you
can link to any package that is hosted on some site and provides Sphinx
docs with some objects.inv file.

Please note that by default you can leave out the :py: domain marker for
Python objects/functions/methods, i.e. you can still write :class:`blah`
instead of :py:class:`blah` because Python is the default domain. See

  http://sphinx.pocoo.org/latest/domains.html

to learn more about Sphinx domains.

Another thing: what about uploading the reference docs for certain
versions of Grok Toolkit to packages.python.org/grok? I think this place
(packages.python.org) could become the default for reference docs of
Python packages in the long run. Only thing is: being splitted up into
grokcore.x packages, I am not sure about whether 'the' grok package will
live forever.

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/20101126/0e2d1e6b/attachment.bin