Implement get_full_qualified_name() to StandardDomain (refs: #3630)

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/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,71 @@ 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'
 
 
 def test_load_mappings_warnings(tempdir, app, status, warning):

tests/test_util_inventory.py

@@ -35,6 +35,7 @@ module2 py:module 0 foo.html#module-$ -
 module1.func py:function 1 sub/foo.html#$ -
 CFunc c:function 2 cfunc.html#CFunc -
 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 -
 a term including:colon std:term -1 glossary.html#term-a-term-including-colon -
 '''.encode('utf-8'))