ENH: Create backreferences for default roles (#1122)

Author: StefRe

doc/configuration.rst

@@ -446,7 +446,9 @@ enables you to link to any examples that either:
    code.
 2. Refer to that function/method/attribute/object/class using sphinx markup
    ``:func:``/``:meth:``/``:attr:``/``:obj:``/``:class:`` in a text
-   block.
+   block. You can omit this role markup if you have set the `default_role
+   <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-default_role>`_
+   in your ``conf.py`` to any of these roles.
 
 The former is useful for auto-documenting functions that are used and classes
 that are explicitly instantiated. The generated links are called implicit

examples/plot_6_function_identifier.py

@@ -29,7 +29,7 @@
 import os.path as op  # noqa, analysis:ignore
 import matplotlib.pyplot as plt
 import sphinx_gallery
-from sphinx_gallery.backreferences import identify_names
+from sphinx_gallery.backreferences import identify_names, _make_ref_regex
 from sphinx_gallery.py_source_parser import split_code_and_text_blocks
 
 filename = 'plot_6_function_identifier.py'
@@ -39,7 +39,7 @@
 
 _, script_blocks = split_code_and_text_blocks(filename)
 
-names = identify_names(script_blocks)
+names = identify_names(script_blocks, _make_ref_regex())
 
 # %%
 # In the code block above, we use the internal function ``identify_names`` to

sphinx_gallery/backreferences.py

@@ -204,17 +204,22 @@ def _get_short_module_name(module_name, obj_name):
     return short_name
 
 
-# keep in synch w/ configuration.rst "Add mini-galleries for API documentation"
-_regex = re.compile(r':(?:'
-                    r'func|'
-                    r'meth|'
-                    r'attr|'
-                    r'obj|'
-                    r'class):`~?(\S*)`'
-                    )
-
-
-def identify_names(script_blocks, global_variables=None, node=''):
+def _make_ref_regex(config=None):
+    """Make regex to find reference to python objects."""
+    # keep roles variable in sync values shown in configuration.rst
+    # "Add mini-galleries for API documentation"
+    roles = 'func|meth|attr|obj|class'
+    default_role = config['default_role'] or '' if config else ''
+    def_role_regex = (
+        '|[^:]?' if re.fullmatch(f'(?:py:)?({roles})', default_role) else ''
+    )
+    # reference can have a separate title `title <reference>`,
+    # don't match ``literal`` or `!disabled.references`
+    return (rf'(?::(?:{roles}):{def_role_regex})'        # role prefix
+            r'(?!``)`~?[^!]*?<?([^!~\s<>`]+)>?(?!``)`')  # reference
+
+
+def identify_names(script_blocks, ref_regex, global_variables=None, node=''):
     """Build a codeobj summary by identifying and resolving used names."""
     if node == '':  # mostly convenience for testing functions
         c = '\n'.join(txt for kind, txt, _ in script_blocks if kind == 'code')
@@ -226,7 +231,9 @@ def identify_names(script_blocks, global_variables=None, node=''):
     names = list(finder.get_mapping())
     # Get matches from docstring inspection (explicit matches)
     text = '\n'.join(txt for kind, txt, _ in script_blocks if kind == 'text')
-    names.extend((x, x, False, False, True) for x in re.findall(_regex, text))
+    names.extend(
+        (x, x, False, False, True) for x in re.findall(ref_regex, text)
+    )
     example_code_obj = collections.OrderedDict()  # order is important
     # Make a list of all guesses, in `_embed_code_links` we will break
     # when we find a match

sphinx_gallery/gen_rst.py

@@ -40,8 +40,8 @@
                     optipng)
 from . import glr_path_static
 from .backreferences import (_write_backreferences, _thumbnail_div,
-                             identify_names, THUMBNAIL_PARENT_DIV,
-                             THUMBNAIL_PARENT_DIV_CLOSE)
+                             identify_names, _make_ref_regex,
+                             THUMBNAIL_PARENT_DIV, THUMBNAIL_PARENT_DIV_CLOSE)
 from .downloads import CODE_DOWNLOAD
 from .py_source_parser import (split_code_and_text_blocks,
                                remove_config_comments,
@@ -1134,7 +1134,9 @@ def generate_file_rst(fname, target_dir, src_dir, gallery_conf,
         global_variables = script_vars['example_globals']
     else:
         global_variables = None
-    example_code_obj = identify_names(script_blocks, global_variables, node)
+    ref_regex = _make_ref_regex(gallery_conf['app'].config)
+    example_code_obj = identify_names(script_blocks, ref_regex,
+                                      global_variables, node)
     if example_code_obj:
         codeobj_fname = target_file[:-3] + '_codeobj.pickle.new'
         with open(codeobj_fname, 'wb') as fid:

sphinx_gallery/tests/conftest.py

@@ -27,8 +27,11 @@ def pytest_report_header(config, startdir):
 @pytest.fixture
 def gallery_conf(tmpdir):
     """Set up a test sphinx-gallery configuration."""
-    app = Mock(spec=Sphinx, config=dict(source_suffix={'.rst': None}),
-               extensions=[])
+    app = Mock(
+        spec=Sphinx,
+        config=dict(source_suffix={".rst": None}, default_role=None),
+        extensions=[],
+    )
     gallery_conf = gen_gallery._fill_gallery_conf_defaults(
         {},  app=app)
     gen_gallery._update_gallery_conf_builder_inited(

sphinx_gallery/tests/test_backreferences.py

@@ -66,7 +66,7 @@ def test_thumbnail_div(content, tooltip, is_backref):
     assert html_div == reference
 
 
-def test_identify_names(unicode_sample):
+def test_identify_names(unicode_sample, gallery_conf):
     """Test name identification."""
     expected = {
         'os.path.join':
@@ -95,12 +95,13 @@ def test_identify_names(unicode_sample):
              }],
     }
     _, script_blocks = split_code_and_text_blocks(unicode_sample)
-    res = sg.identify_names(script_blocks)
+    ref_regex = sg._make_ref_regex(gallery_conf['app'].config)
+    res = sg.identify_names(script_blocks, ref_regex)
     assert expected == res
 
 
-def test_identify_names2(tmpdir):
-    """Test more name identification."""
+def test_identify_names_implicit(tmpdir, gallery_conf):
+    """Test implicit name identification."""
     code_str = b"""
 '''
 Title
@@ -148,26 +149,52 @@ def test_identify_names2(tmpdir):
     fname.write(code_str, 'wb')
 
     _, script_blocks = split_code_and_text_blocks(fname.strpath)
-    res = sg.identify_names(script_blocks)
+    ref_regex = sg._make_ref_regex(gallery_conf['app'].config)
+    res = sg.identify_names(script_blocks, ref_regex)
 
     assert expected == res
 
-    code_str = b"""
-'''
-Title
------
-
-This example uses :func:`k.l` and :meth:`~m.n`.
-'''
-""" + code_str.split(b"'''")[-1]
-    expected['k.l'] = [{'module': 'k', 'module_short': 'k', 'name': 'l',
-                        'is_class': False, 'is_explicit': True}]
-    expected['m.n'] = [{'module': 'm', 'module_short': 'm', 'name': 'n',
-                        'is_class': False, 'is_explicit': True}]
 
-    fname = tmpdir.join("identify_names.py")
-    fname.write(code_str, 'wb')
-    _, script_blocks = split_code_and_text_blocks(fname.strpath)
-    res = sg.identify_names(script_blocks)
-
-    assert expected == res
+cobj = dict(
+    module="m", module_short="m", name="n", is_class=False, is_explicit=True
+)
+
+
+@pytest.mark.parametrize(
+    'text, default_role, ref, cobj',
+    [
+        (':func:`m.n`', None, 'm.n', cobj),
+        (':func:`~m.n`', 'obj', 'm.n', cobj),
+        (':func:`Title <m.n>`', None, 'm.n', cobj),
+        (':func:`!m.n` or `!t <~m.n>`', None, None, None),
+        ('`m.n`', 'obj', 'm.n', cobj),
+        ('`m.n`', None, None, None),  # see comment below
+        (':ref:`m.n`', None, None, None),
+        ('`m.n`', 'ref', None, None),
+        ('``literal``', 'obj', None, None),
+    ],
+    ids=[
+        'regular',
+        'show only last component',
+        'with title',
+        'no link for !',
+        'default_role obj',
+        'no default_role',  # see comment below
+        'non-python role',
+        'non-python default_role',
+        'literal',
+    ],
+)
+# the sphinx default value for default_role is None = no change, the docutils
+# default is title-reference (set by the default-role directive), see
+# www.sphinx-doc.org/en/master/usage/configuration.html#confval-default_role
+# and docutils.sourceforge.io/docs/ref/rst/roles.html
+def test_identify_names_explicit(text, default_role, ref, cobj, gallery_conf):
+    """Test explicit name identification."""
+    if default_role:
+        gallery_conf['app'].config['default_role'] = default_role
+    script_blocks = [('text', text, 1)]
+    expected = {ref: [cobj]} if ref else {}
+    ref_regex = sg._make_ref_regex(gallery_conf['app'].config)
+    actual = sg.identify_names(script_blocks, ref_regex)
+    assert expected == actual

sphinx_gallery/tests/tinybuild/examples/plot_numpy_matplotlib.py

@@ -39,7 +39,9 @@
 # nested resolution resolves to numpy.random.mtrand.RandomState:
 rng = np.random.RandomState(0)
 # test Issue 583
-sphinx_gallery.backreferences.identify_names([('text', 'Text block', 1)])
+sphinx_gallery.backreferences.identify_names(
+    [('text', 'Text block', 1)],
+    sphinx_gallery.backreferences._make_ref_regex({'default_role': None}))
 # 583: methods don't link properly
 dc = sphinx_gallery.backreferences.DummyClass()
 dc.run()