Comment 4 for bug 1246713

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.