From 01c501054e4e42e2c614c7a244f8b769938909f8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Aug 2010 11:58:43 +0200 Subject: [PATCH] #480: Fix handling of target naming in intersphinx. --- CHANGES | 2 ++ doc/conf.py | 2 ++ doc/ext/intersphinx.rst | 6 ++-- sphinx/ext/intersphinx.py | 17 +++++++++-- tests/test_intersphinx.py | 60 +++++++++++++++++++++++---------------- 5 files changed, 57 insertions(+), 30 deletions(-) diff --git a/CHANGES b/CHANGES index dce6e713a..cb80d72c6 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,8 @@ Release 1.0.2 (in development) ============================== +* #480: Fix handling of target naming in intersphinx. + * #486: Fix removal of ``!`` for all cross-reference roles. diff --git a/doc/conf.py b/doc/conf.py index 299f321ac..21e8d2f54 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -8,6 +8,8 @@ import sphinx extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.autosummary', 'sphinx.ext.extlinks'] +#intersphinx_mapping = {'python': ('http://docs.python.org/dev', None)} + master_doc = 'contents' templates_path = ['_templates'] exclude_patterns = ['_build'] diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index bb2a5a8c4..7997472a7 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -84,7 +84,7 @@ linking: To add links to modules and objects in the Python standard library documentation, use:: - intersphinx_mapping = {'python': ('http://docs.python.org/', None)} + intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)} This will download the corresponding :file:`objects.inv` file from the Internet and generate links to the pages under the given URI. The downloaded @@ -94,12 +94,12 @@ linking: A second example, showing the meaning of a non-``None`` value of the second tuple item:: - intersphinx_mapping = {'python': ('http://docs.python.org/', + intersphinx_mapping = {'python': ('http://docs.python.org/3.2', 'python-inv.txt')} This will read the inventory from :file:`python-inv.txt` in the source directory, but still generate links to the pages under - ``http://docs.python.org/``. It is up to you to update the inventory file as + ``http://docs.python.org/3.2``. It is up to you to update the inventory file as new objects are added to the Python documentation. .. confval:: intersphinx_cache_limit diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index 0a210879a..055fc9cd9 100644 --- a/sphinx/ext/intersphinx.py +++ b/sphinx/ext/intersphinx.py @@ -205,9 +205,20 @@ def missing_reference(app, env, node, contnode): proj, version, uri, dispname = inventory[objtype][target] newnode = nodes.reference('', '', internal=False, refuri=uri, reftitle='(in %s v%s)' % (proj, version)) - if dispname == '-': - dispname = target - newnode.append(contnode.__class__(dispname, dispname)) + if node.get('refexplicit'): + # use whatever title was given + newnode.append(contnode) + elif dispname == '-': + # 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:])) + else: + newnode.append(contnode) + else: + # else use the given display name (used for :ref:) + newnode.append(contnode.__class__(dispname, dispname)) return newnode # at least get rid of the ':' in the target if no explicit title given if in_set is not None and not node.get('refexplicit', True): diff --git a/tests/test_intersphinx.py b/tests/test_intersphinx.py index 8b6547e54..3b50cc78c 100644 --- a/tests/test_intersphinx.py +++ b/tests/test_intersphinx.py @@ -94,46 +94,58 @@ def test_missing_reference(tempdir, app): ('foo', '2.0', 'http://docs.python.org/foo.html#module-module2', '-') # create fake nodes and check referencing - contnode = nodes.emphasis('foo', 'foo') - refnode = addnodes.pending_xref('') - refnode['reftarget'] = 'module1.func' - refnode['reftype'] = 'func' - refnode['refdomain'] = 'py' - rn = missing_reference(app, app.env, refnode, contnode) + def fake_node(domain, type, target, content, **attrs): + contnode = nodes.emphasis(content, content) + node = addnodes.pending_xref('') + node['reftarget'] = target + node['reftype'] = type + node['refdomain'] = domain + node.attributes.update(attrs) + node += contnode + return node, contnode + + def reference_check(*args, **kwds): + node, contnode = fake_node(*args, **kwds) + return missing_reference(app, app.env, node, contnode) + + # check resolution when a target is found + rn = reference_check('py', 'func', 'module1.func', 'foo') assert isinstance(rn, nodes.reference) assert rn['refuri'] == 'http://docs.python.org/sub/foo.html#module1.func' assert rn['reftitle'] == '(in foo v2.0)' - assert rn[0].astext() == 'module1.func' + assert rn[0].astext() == 'foo' # create unresolvable nodes and check None return value - refnode['reftype'] = 'foo' - assert missing_reference(app, app.env, refnode, contnode) is None - - refnode['reftype'] = 'function' - refnode['reftarget'] = 'foo.func' - assert missing_reference(app, app.env, refnode, contnode) is None + assert reference_check('py', 'foo', 'module1.func', 'foo') is None + assert reference_check('py', 'func', 'foo', 'foo') is None + assert reference_check('py', 'func', 'foo', 'foo') is None # check handling of prefixes # prefix given, target found: prefix is stripped - refnode['reftype'] = 'mod' - refnode['reftarget'] = 'py3k:module2' - rn = missing_reference(app, app.env, refnode, contnode) + rn = reference_check('py', 'mod', 'py3k:module2', 'py3k:module2') assert rn[0].astext() == 'module2' + # prefix given, but not in title: nothing stripped + rn = reference_check('py', 'mod', 'py3k:module2', 'module2') + assert rn[0].astext() == 'module2' + + # prefix given, but explicit: nothing stripped + rn = reference_check('py', 'mod', 'py3k:module2', 'py3k:module2', + refexplicit=True) + assert rn[0].astext() == 'py3k:module2' + # prefix given, target not found and nonexplicit title: prefix is stripped - refnode['reftarget'] = 'py3k:unknown' - refnode['refexplicit'] = False - contnode[0] = nodes.Text('py3k:unknown') - rn = missing_reference(app, app.env, refnode, contnode) + node, contnode = fake_node('py', 'mod', 'py3k:unknown', 'py3k:unknown', + refexplicit=False) + rn = missing_reference(app, app.env, node, contnode) assert rn is None assert contnode[0].astext() == 'unknown' # prefix given, target not found and explicit title: nothing is changed - refnode['reftarget'] = 'py3k:unknown' - refnode['refexplicit'] = True - contnode[0] = nodes.Text('py3k:unknown') - rn = missing_reference(app, app.env, refnode, contnode) + node, contnode = fake_node('py', 'mod', 'py3k:unknown', 'py3k:unknown', + refexplicit=True) + rn = missing_reference(app, app.env, node, contnode) assert rn is None assert contnode[0].astext() == 'py3k:unknown'