Ability to link to third-party projects

[Laurens Van Houtven]

There should be a way to link to code that isn't in the current project or in the stdlib. I ran into this in http://tm.tl/6803 when trying to document twisted.conch; it links to stuff in PyCrypto.

[Glyph Lefkowitz (glyph)]

I ran into this again on <https://tm.tl/7098>.

[Michael Hudson-Doyle (mwhudson)]

The way to fix this is to support sphinx's "objects.inv" format.

I'm not sure when the spare time and the spare enthusiasm are going to coincide to get this done, unfortunately :/

[Adi Roiban (adiroiban)]

OK. How do you want this to be solved?

I think that this needs to be split into 2 tickets:
One for something similar to intersphinx and another similar for extlinks

---------------

For intersphix, we need some sort of configuration:

intersphinx_mapping = {
      'Crypto' : ('http://py.crypto.com/api', None)
      'twisted: ('http://tm.tld/documentation/current/api', None)
      }

When it fails to resole L{Crypto.some.stuff} it can check intersphinx inventory.
Same for unresolved L{twisted.some.other.stuff}.

Note that this only works for project using Sphinx for api...

--------

For extlinks, we need a mapping

extlinks = {'Crypto': 'http://pythonhosted.org/pycrypto/%s.html'}

So that unresolved L{Crypto.some.thing} will link to http://pythonhosted.org/pycrypto/Crypto.some.thing.html

One option for extlinks is to map it to a function:

extlinks = {'Crypto': 'plugin:crypto_resolver.mapper'}

def crypto_resolver(name):
    return '%s/%s' % ('http://base', '/'.join(name.split('.')))

crypt_resolver could then do a trial and error and check remote URL for name-module.html or name-class.html and return only valid links... this will be slow... but should be flexible.

If exlinkg mapping start with plugin: it will try to import that method.

---------

I see that PyCrypto uses epydocs and not pydoctor... so it does not have an objects.inv...

Also, epydocs produces some ugly urls ... Crypto.Cipher.AES.AESCipher-class.html and Crypto.Cipher.blockalgo-module.html .. so is not easy to create a simple mapping

---------

I will keep this ticket for linking to generic 3rd party apis and will create a new ticket targeted for supporting intersphinx objects.inv

[Michael Hudson-Doyle (mwhudson)]

Adi Roiban <email address hidden> writes:

> OK. How do you want this to be solved?
>
> I think that this needs to be split into 2 tickets:
> One for something similar to intersphinx and another similar for extlinks

Ah yes. I'd only really been thinking about intersphinx.

> ---------------
>
> For intersphix, we need some sort of configuration:
>
> intersphinx_mapping = {
> 'Crypto' : ('http://py.crypto.com/api', None)
> 'twisted: ('http://tm.tld/documentation/current/api', None)
> }
>
> When it fails to resole L{Crypto.some.stuff} it can check intersphinx inventory.
> Same for unresolved L{twisted.some.other.stuff}.
>
> Note that this only works for project using Sphinx for api...
>
> --------
>
> For extlinks, we need a mapping
>
> extlinks = {'Crypto': 'http://pythonhosted.org/pycrypto/%s.html'}
>
> So that unresolved L{Crypto.some.thing} will link to
> http://pythonhosted.org/pycrypto/Crypto.some.thing.html
>
> One option for extlinks is to map it to a function:
>
> extlinks = {'Crypto': 'plugin:crypto_resolver.mapper'}
>
> def crypto_resolver(name):
> return '%s/%s' % ('http://base', '/'.join(name.split('.')))
>
> crypt_resolver could then do a trial and error and check remote URL for
> name-module.html or name-class.html and return only valid links... this
> will be slow... but should be flexible.
>
> If exlinkg mapping start with plugin: it will try to import that
> method.
>
> ---------
>
> I see that PyCrypto uses epydocs and not pydoctor... so it does not have an objects.inv...
>
> Also, epydocs produces some ugly urls ... Crypto.Cipher.AES.AESCipher-class.html and Crypto.Cipher.blockalgo-module.html .. so is not easy to create a simple mapping

How many different things do we want to support here? Can we just add
support for intersphinx and then add support for epydoc? (I guess
epydoc is hard because you don't know from
L{Crypto.Cipher.AES.AESCipher} that it's a class. Does epydoc itself
support x-project linking?).

> I will keep this ticket for linking to generic 3rd party apis and will
> create a new ticket targeted for supporting intersphinx objects.inv

Cool, thanks.