intersphinx links must be fully qualified

[wence-]

I use intersphinx to link to other bits of documentation.

I would like to be able to write :class:firedrake:.Function and have this resolved, in the same way it would be by Sphinx in the "foreign" documentation, into (in this case) firedrake.function.Function. Currently intersphinx only links correctly if I put in the fully qualified object name. This can be rather tiresome.

If I understand the code to some level, I think one needs to update missing_reference in intersphinx to handle this case in the same way that (say) PythonDomain.find_obj works. However, I can't just use that code directly, since the currently active domain inside env knows nothing about the intersphinx inventorys.

A hacky "fix" for this might be something like:

diff -u /data/lmitche1/src/firedrake/lib/python2.7/site-packages/sphinx/ext/intersphinx.py.bak /data/lmitche1/src/firedrake/lib/python2.7/site-packages/sphinx/ext/intersphinx.py
--- /data/lmitche1/src/firedrake/lib/python2.7/site-packages/sphinx/ext/intersphinx.py.bak	2017-01-18 13:02:28.528827706 +0000
+++ /data/lmitche1/src/firedrake/lib/python2.7/site-packages/sphinx/ext/intersphinx.py	2017-01-18 12:56:12.877045837 +0000
@@ -326,9 +326,22 @@
             in_set = setname
             to_try.append((env.intersphinx_named_inventory[setname], newtarget))
     for inventory, target in to_try:
+        fuzzy = target.startswith(".")
         for objtype in objtypes:
-            if objtype not in inventory or target not in inventory[objtype]:
+            if objtype not in inventory:
                 continue
+            if target not in inventory[objtype] and not fuzzy:
+                continue
+            if fuzzy:
+                matches = [key for key in inventory[objtype] if key.endswith(target)]
+                if len(matches) > 1:
+                    env.warn_node(
+                        'more than one target found for cross-reference '
+                        '%r: %s' % (target, ', '.join(match for match in matches)),
+                        node)
+                if not matches:
+                    continue
+                target = matches[0]
             proj, version, uri, dispname = inventory[objtype][target]
             if '://' not in uri and node.get('refdoc'):
                 # get correct path in case of subdirectories
@@ -343,8 +356,11 @@
                 # use whatever title was given, but strip prefix
                 title = contnode.astext()
                 if in_set and title.startswith(in_set+':'):
-                    newnode.append(contnode.__class__(title[len(in_set)+1:],
-                                                      title[len(in_set)+1:]))
+                    if fuzzy:
+                        title = target
+                    else:
+                        title = title[len(in_set)+1:]
+                    newnode.append(contnode.__class__(title, title))
                 else:
                     newnode.append(contnode)
             else:

Diff finished.  Wed Jan 18 13:02:49 2017

But I'm not really very happy, and this seems unlikely to work with domains other that Python. Thoughts, suggestions?

[tk0miya]

Usually, we use .. py:module:: directive to give search path for python objects in python domain.

.. py:class:: foo.bar.MyClass

   text text text ...

.. py:module:: foo.bar

:py:class:`MyClass`  # succeed to refer!

But, at this moment, intersphinx does not refers the context.
I feel to fix it is a solution for this problem.

[bitprophet]

I've struggled with this forever myself; honestly a bit surprised a ticket hasn't existed before now. Not a Sphinx internals developer, but the approach in #3425 is the sort of approach I would have tried if I'd attempted my own PR 👍