Issue #1204 resolved

relative target path for intersphinx leads to broken links

Dan Callaghan
created an issue

The intersphinx docs say: "Relative local paths for target locations are taken as relative to the base of the built documentation". But that doesn't work when the document is in a subdirectory. The href should have ../ prepended as many times as needed, but it doesn't.

For example, an intersphinx mapping like this:

intersphinx_mapping = {
    'other': ('../other/', '../other/other.inv'),

when used in a document such as topic/details.rst, will link to ../other/something whereas it should link to ../../other/something.

I had a go at fixing this myself, I got as far as figuring out that it should be calling app.builder.get_relative_uri, something like this:

--- a/sphinx/ext/
+++ b/sphinx/ext/
@@ -220,7 +220,8 @@ def missing_reference(app, env, node, contnode):
             if objtype not in inventory or target not in inventory[objtype]:
             proj, version, uri, dispname = inventory[objtype][target]
-            newnode = nodes.reference('', '', internal=False, refuri=uri,
+            newnode = nodes.reference('', '', internal=False,
+                          refuri=app.builder.get_relative_uri('WHAT GOES HERE?', uri),
                           reftitle=_('(in %s v%s)') % (proj, version))
             if node.get('refexplicit'):
                 # use whatever title was given

but I can't figure out how the missing_reference hook can tell what the source document path is (I was expecting I could do something like but that is not a thing).

Comments (5)

  1. WAKAYAMA shirou

    Currently intersphinx assumes the base directory is the build output dir.

    So I think you rewrite the intersphinx_mapping in the to relative path from the build output dir (../../other/something).

    If add get_relative_uri() by your suggestion, some other documents may become broken.

  2. Log in to comment