Merge pull request #3658 from tk0miya/3630_add_get_full_qualified_names

Add get_full_qualified_names() to std, js and cpp domains.

sphinx/domains/cpp.py

@@ -5032,6 +5032,20 @@ class CPPDomain(Domain):
             newestId = symbol.declaration.get_newest_id()
             yield (name, name, objectType, docname, newestId, 1)
 
+    def get_full_qualified_name(self, node):
+        # type: (nodes.Node) -> unicode
+        target = node.get('reftarget', None)
+        if target is None:
+            return None
+        parentKey = node.get("cpp:parent_key", None)
+        if parentKey is None:
+            return None
+
+        rootSymbol = self.data['root_symbol']
+        parentSymbol = rootSymbol.direct_lookup(parentKey)
+        parentName = parentSymbol.get_full_nested_name()
+        return '::'.join([text_type(parentName), target])
+
 
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]

sphinx/domains/javascript.py

@@ -398,6 +398,16 @@ class JavaScriptDomain(Domain):
             yield refname, refname, type, docname, \
                 refname.replace('$', '_S_'), 1
 
+    def get_full_qualified_name(self, node):
+        # type: (nodes.Node) -> unicode
+        modname = node.get('js:module')
+        prefix = node.get('js:object')
+        target = node.get('reftarget')
+        if target is None:
+            return None
+        else:
+            return '.'.join(filter(None, [modname, prefix, target]))
+
 
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]

sphinx/domains/std.py

@@ -849,7 +849,11 @@ class StandardDomain(Domain):
         for doc in self.env.all_docs:
             yield (doc, clean_astext(self.env.titles[doc]), 'doc', doc, '', -1)
         for (prog, option), info in iteritems(self.data['progoptions']):
-            yield (option, option, 'cmdoption', info[0], info[1], 1)
+            if prog:
+                fullname = ".".join([prog, option])
+                yield (fullname, fullname, 'cmdoption', info[0], info[1], 1)
+            else:
+                yield (option, option, 'cmdoption', info[0], info[1], 1)
         for (type, name), info in iteritems(self.data['objects']):
             yield (name, name, type, info[0], info[1],
                    self.object_types[type].attrs['searchprio'])
@@ -925,6 +929,15 @@ class StandardDomain(Domain):
                 # Maybe it is defined in orphaned document.
                 raise ValueError
 
+    def get_full_qualified_name(self, node):
+        # type: (nodes.Node) -> unicode
+        progname = node.get('std:program')
+        target = node.get('reftarget')
+        if progname is None or target is None:
+            return None
+        else:
+            return '.'.join([progname, target])
+
 
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]

tests/roots/test-ext-intersphinx-cppdomain/conf.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+extensions = ['sphinx.ext.intersphinx']
+master_doc = 'index'

tests/roots/test-ext-intersphinx-cppdomain/index.rst

@@ -0,0 +1,6 @@
+test-ext-intersphinx-cppdomain
+==============================
+
+.. cpp:namespace:: foo
+
+:cpp:class:`Bar`

tests/test_domain_js.py

@@ -10,7 +10,11 @@
 """
 
 import pytest
+from mock import Mock
+from docutils import nodes
+
 from sphinx import addnodes
+from sphinx.domains.javascript import JavaScriptDomain
 
 from util import assert_node
 
@@ -133,3 +137,31 @@ def test_domain_js_find_obj(app, status, warning):
             ( u'module_a.submodule.ModTopLevel.mod_child_2', (u'module', u'method')))
     assert (find_obj(u'module_b.submodule', u'ModTopLevel', u'module_a.submodule', u'mod') ==
             ( u'module_a.submodule', (u'module', u'module')))
+
+
+def test_get_full_qualified_name():
+    env = Mock(domaindata={})
+    domain = JavaScriptDomain(env)
+
+    # non-js references
+    node = nodes.reference()
+    assert domain.get_full_qualified_name(node) is None
+
+    # simple reference
+    node = nodes.reference(reftarget='func')
+    assert domain.get_full_qualified_name(node) == 'func'
+
+    # with js:module context
+    kwargs = {'js:module': 'module1'}
+    node = nodes.reference(reftarget='func', **kwargs)
+    assert domain.get_full_qualified_name(node) == 'module1.func'
+
+    # with js:object context
+    kwargs = {'js:object': 'Class'}
+    node = nodes.reference(reftarget='func', **kwargs)
+    assert domain.get_full_qualified_name(node) == 'Class.func'
+
+    # with both js:module and js:object context
+    kwargs = {'js:module': 'module1', 'js:object': 'Class'}
+    node = nodes.reference(reftarget='func', **kwargs)
+    assert domain.get_full_qualified_name(node) == 'module1.Class.func'

tests/test_domain_std.py

@@ -57,3 +57,21 @@ def test_process_doc_handle_table_title():
     assert 'testname' in domain.data['labels']
     assert domain.data['labels']['testname'] == (
         'testdoc', 'testid', 'title text')
+
+
+def test_get_full_qualified_name():
+    env = mock.Mock(domaindata={})
+    domain = StandardDomain(env)
+
+    # normal references
+    node = nodes.reference()
+    assert domain.get_full_qualified_name(node) is None
+
+    # simple reference to options
+    node = nodes.reference(reftype='option', reftarget='-l')
+    assert domain.get_full_qualified_name(node) is None
+
+    # options with std:program context
+    kwargs = {'std:program': 'ls'}
+    node = nodes.reference(reftype='option', reftarget='-l', **kwargs)
+    assert domain.get_full_qualified_name(node) == 'ls.-l'

tests/test_ext_intersphinx.py

@@ -26,6 +26,22 @@ from sphinx.ext.intersphinx import (
 from test_util_inventory import inventory_v2
 
 
+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(app, *args, **kwds):
+    node, contnode = fake_node(*args, **kwds)
+    return missing_reference(app, app.env, node, contnode)
+
+
 @mock.patch('sphinx.ext.intersphinx.InventoryFile')
 @mock.patch('sphinx.ext.intersphinx._read_from_url')
 def test_fetch_inventory_redirection(_read_from_url, InventoryFile, app, status, warning):
@@ -88,46 +104,30 @@ def test_missing_reference(tempdir, app, status, warning):
     assert inv['py:module']['module2'] == \
         ('foo', '2.0', 'https://docs.python.org/foo.html#module-module2', '-')
 
-    # create fake nodes and check referencing
-
-    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')
+    rn = reference_check(app, 'py', 'func', 'module1.func', 'foo')
     assert isinstance(rn, nodes.reference)
     assert rn['refuri'] == 'https://docs.python.org/sub/foo.html#module1.func'
     assert rn['reftitle'] == '(in foo v2.0)'
     assert rn[0].astext() == 'foo'
 
     # create unresolvable nodes and check None return value
-    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
+    assert reference_check(app, 'py', 'foo', 'module1.func', 'foo') is None
+    assert reference_check(app, 'py', 'func', 'foo', 'foo') is None
+    assert reference_check(app, 'py', 'func', 'foo', 'foo') is None
 
     # check handling of prefixes
 
     # prefix given, target found: prefix is stripped
-    rn = reference_check('py', 'mod', 'py3k:module2', 'py3k:module2')
+    rn = reference_check(app, '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')
+    rn = reference_check(app, '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',
+    rn = reference_check(app, 'py', 'mod', 'py3k:module2', 'py3k:module2',
                          refexplicit=True)
     assert rn[0].astext() == 'py3k:module2'
 
@@ -145,34 +145,115 @@ def test_missing_reference(tempdir, app, status, warning):
     assert rn is None
     assert contnode[0].astext() == 'py3k:unknown'
 
+    # check relative paths
+    rn = reference_check(app, 'py', 'mod', 'py3krel:module1', 'foo')
+    assert rn['refuri'] == 'py3k/foo.html#module-module1'
+
+    rn = reference_check(app, 'py', 'mod', 'py3krelparent:module1', 'foo')
+    assert rn['refuri'] == '../../py3k/foo.html#module-module1'
+
+    rn = reference_check(app, 'py', 'mod', 'py3krel:module1', 'foo', refdoc='sub/dir/test')
+    assert rn['refuri'] == '../../py3k/foo.html#module-module1'
+
+    rn = reference_check(app, 'py', 'mod', 'py3krelparent:module1', 'foo',
+                         refdoc='sub/dir/test')
+    assert rn['refuri'] == '../../../../py3k/foo.html#module-module1'
+
+    # check refs of standard domain
+    rn = reference_check(app, 'std', 'doc', 'docname', 'docname')
+    assert rn['refuri'] == 'https://docs.python.org/docname.html'
+
+
+def test_missing_reference_pydomain(tempdir, app, status, warning):
+    inv_file = tempdir / 'inventory'
+    inv_file.write_bytes(inventory_v2)
+    app.config.intersphinx_mapping = {
+        'https://docs.python.org/': inv_file,
+    }
+    app.config.intersphinx_cache_limit = 0
+
+    # load the inventory and check if it's done correctly
+    load_mappings(app)
+
     # no context data
     kwargs = {}
     node, contnode = fake_node('py', 'func', 'func', 'func()', **kwargs)
     rn = missing_reference(app, app.env, node, contnode)
     assert rn is None
 
-    # context data (like py:module) help to search objects
+    # py:module context helps to search objects
     kwargs = {'py:module': 'module1'}
     node, contnode = fake_node('py', 'func', 'func', 'func()', **kwargs)
     rn = missing_reference(app, app.env, node, contnode)
-    assert rn[0].astext() == 'func()'
+    assert rn.astext() == 'func()'
 
-    # check relative paths
-    rn = reference_check('py', 'mod', 'py3krel:module1', 'foo')
-    assert rn['refuri'] == 'py3k/foo.html#module-module1'
 
-    rn = reference_check('py', 'mod', 'py3krelparent:module1', 'foo')
-    assert rn['refuri'] == '../../py3k/foo.html#module-module1'
+def test_missing_reference_stddomain(tempdir, app, status, warning):
+    inv_file = tempdir / 'inventory'
+    inv_file.write_bytes(inventory_v2)
+    app.config.intersphinx_mapping = {
+        'https://docs.python.org/': inv_file,
+    }
+    app.config.intersphinx_cache_limit = 0
 
-    rn = reference_check('py', 'mod', 'py3krel:module1', 'foo', refdoc='sub/dir/test')
-    assert rn['refuri'] == '../../py3k/foo.html#module-module1'
+    # load the inventory and check if it's done correctly
+    load_mappings(app)
 
-    rn = reference_check('py', 'mod', 'py3krelparent:module1', 'foo', refdoc='sub/dir/test')
-    assert rn['refuri'] == '../../../../py3k/foo.html#module-module1'
+    # no context data
+    kwargs = {}
+    node, contnode = fake_node('std', 'option', '-l', '-l', **kwargs)
+    rn = missing_reference(app, app.env, node, contnode)
+    assert rn is None
 
-    # check refs of standard domain
-    rn = reference_check('std', 'doc', 'docname', 'docname')
-    assert rn['refuri'] == 'https://docs.python.org/docname.html'
+    # std:program context helps to search objects
+    kwargs = {'std:program': 'ls'}
+    node, contnode = fake_node('std', 'option', '-l', 'ls -l', **kwargs)
+    rn = missing_reference(app, app.env, node, contnode)
+    assert rn.astext() == 'ls -l'
+
+
+@pytest.mark.sphinx('html', testroot='ext-intersphinx-cppdomain')
+def test_missing_reference_cppdomain(tempdir, app, status, warning):
+    inv_file = tempdir / 'inventory'
+    inv_file.write_bytes(inventory_v2)
+    app.config.intersphinx_mapping = {
+        'https://docs.python.org/': inv_file,
+    }
+    app.config.intersphinx_cache_limit = 0
+
+    # load the inventory and check if it's done correctly
+    load_mappings(app)
+
+    app.build()
+    html = (app.outdir / 'index.html').text()
+    assert ('<a class="reference external"'
+            ' href="https://docs.python.org/index.html#cpp_foo_bar"'
+            ' title="(in foo v2.0)"><code class="xref cpp cpp-class docutils literal">'
+            '<span class="pre">Bar</span></code></a>' in html)
+
+
+def test_missing_reference_jsdomain(tempdir, app, status, warning):
+    inv_file = tempdir / 'inventory'
+    inv_file.write_bytes(inventory_v2)
+    app.config.intersphinx_mapping = {
+        'https://docs.python.org/': inv_file,
+    }
+    app.config.intersphinx_cache_limit = 0
+
+    # load the inventory and check if it's done correctly
+    load_mappings(app)
+
+    # no context data
+    kwargs = {}
+    node, contnode = fake_node('js', 'meth', 'baz', 'baz()', **kwargs)
+    rn = missing_reference(app, app.env, node, contnode)
+    assert rn is None
+
+    # js:module and js:object context helps to search objects
+    kwargs = {'js:module': 'foo', 'js:object': 'bar'}
+    node, contnode = fake_node('js', 'meth', 'baz', 'baz()', **kwargs)
+    rn = missing_reference(app, app.env, node, contnode)
+    assert rn.astext() == 'baz()'
 
 
 def test_load_mappings_warnings(tempdir, app, status, warning):

tests/test_util_inventory.py

@@ -34,8 +34,15 @@ module1 py:module 0 foo.html#module-module1 Long Module desc
 module2 py:module 0 foo.html#module-$ -
 module1.func py:function 1 sub/foo.html#$ -
 CFunc c:function 2 cfunc.html#CFunc -
+foo::Bar cpp:class 1 index.html#cpp_foo_bar -
+foo::Bar::baz cpp:function 1 index.html#cpp_foo_bar_baz -
 a term std:term -1 glossary.html#term-a-term -
+ls.-l std:cmdoption 1 index.html#cmdoption-ls-l -
 docname std:doc -1 docname.html -
+foo js:module 1 index.html#foo -
+foo.bar js:class 1 index.html#foo.bar -
+foo.bar.baz js:method 1 index.html#foo.bar.baz -
+foo.bar.qux js:data 1 index.html#foo.bar.qux -
 a term including:colon std:term -1 glossary.html#term-a-term-including-colon -
 '''.encode('utf-8'))