WIP: kwarg to ignore unknown terms in make_xref.

Add a kwarg to make_xref to toggle the automatic wrapping of every term
not in xref_ignore in an :obj: role.

Author: rossbar

numpydoc/tests/test_xref.py

@@ -102,6 +102,101 @@
 :class:`python:dict`\[:class:`python:tuple`\(:class:`python:str`, :class:`python:str`), :class:`python:int`]
 """  # noqa: E501
 
+data_ignore_obj = r"""
+(...) array_like, float, optional
+(...) :term:`numpy:array_like`, :class:`python:float`, optional
+
+(2,) ndarray
+(2,) :obj:`ndarray <numpy.ndarray>`
+
+(...,M,N) array_like
+(...,M,N) :term:`numpy:array_like`
+
+(..., M, N) array_like
+(..., M, N) :term:`numpy:array_like`
+
+(float, float), optional
+(:class:`python:float`, :class:`python:float`), optional
+
+1-D array or sequence
+1-D :obj:`array <numpy.ndarray>` or :term:`python:sequence`
+
+array of str or unicode-like
+:obj:`array <numpy.ndarray>` of :class:`python:str` or unicode-like
+
+array_like of float
+:term:`numpy:array_like` of :class:`python:float`
+
+bool or callable
+:ref:`bool <python:bltin-boolean-values>` or :func:`python:callable`
+
+int in [0, 255]
+:class:`python:int` in [0, 255]
+
+int or None, optional
+:class:`python:int` or :data:`python:None`, optional
+
+list of str or array_like
+:class:`python:list` of :class:`python:str` or :term:`numpy:array_like`
+
+sequence of array_like
+:term:`python:sequence` of :term:`numpy:array_like`
+
+str or pathlib.Path
+:class:`python:str` or pathlib.Path
+
+{'', string}, optional
+{'', :class:`python:str`}, optional
+
+{'C', 'F', 'A', or 'K'}, optional
+{'C', 'F', 'A', or 'K'}, optional
+
+{'linear', 'lower', 'higher', 'midpoint', 'nearest'}
+{'linear', 'lower', 'higher', 'midpoint', 'nearest'}
+
+{False, True, 'greedy', 'optimal'}
+{:data:`python:False`, :data:`python:True`, 'greedy', 'optimal'}
+
+{{'begin', 1}, {'end', 0}}, {string, int}
+{{'begin', 1}, {'end', 0}}, {:class:`python:str`, :class:`python:int`}
+
+callable f'(x,*args)
+:func:`python:callable` f'(x,*args)
+
+callable ``fhess(x, *args)``, optional
+:func:`python:callable` ``fhess(x, *args)``, optional
+
+spmatrix (format: ``csr``, ``bsr``, ``dia`` or coo``)
+spmatrix (format: ``csr``, ``bsr``, ``dia`` or coo``)
+
+:ref:`strftime <strftime-strptime-behavior>`
+:ref:`strftime <strftime-strptime-behavior>`
+
+callable or :ref:`strftime <strftime-strptime-behavior>`
+:func:`python:callable` or :ref:`strftime <strftime-strptime-behavior>`
+
+callable or :ref:`strftime behavior <strftime-strptime-behavior>`
+:func:`python:callable` or :ref:`strftime behavior <strftime-strptime-behavior>`
+
+list(int)
+:class:`python:list`\(:class:`python:int`)
+
+list[int]
+:class:`python:list`\[:class:`python:int`]
+
+dict(str, int)
+:class:`python:dict`\(:class:`python:str`, :class:`python:int`)
+
+dict[str,  int]
+:class:`python:dict`\[:class:`python:str`,  :class:`python:int`]
+
+tuple(float, float)
+:class:`python:tuple`\(:class:`python:float`, :class:`python:float`)
+
+dict[tuple(str, str), int]
+:class:`python:dict`\[:class:`python:tuple`\(:class:`python:str`, :class:`python:str`), :class:`python:int`]
+"""  # noqa: E501
+
 xref_ignore = {'or', 'in', 'of', 'default', 'optional'}
 
 
@@ -111,3 +206,10 @@
 )
 def test_make_xref(param_type, expected_result):
     assert make_xref(param_type, xref_aliases, xref_ignore) == expected_result
+
+@pytest.mark.parametrize(
+    ('param_type', 'expected_result'),
+    [tuple(s.split('\n')) for s in data_ignore_obj.strip().split('\n\n')]
+)
+def test_make_xref_ignore_unknown(param_type, expected_result):
+    assert make_xref(param_type, xref_aliases, xref_ignore, wrap_unknown=False) == expected_result

numpydoc/xref.py

@@ -94,7 +94,7 @@
 }
 
 
-def make_xref(param_type, xref_aliases, xref_ignore):
+def make_xref(param_type, xref_aliases, xref_ignore, wrap_unknown=True):
     """Parse and apply appropriate sphinx role(s) to `param_type`.
 
     The :obj: role is the default.
@@ -124,8 +124,9 @@ def make_xref(param_type, xref_aliases, xref_ignore):
     if QUALIFIED_NAME_RE.match(link) and link not in xref_ignore:
         if link != title:
             return ':obj:`%s <%s>`' % (title, link)
-        else:
+        if wrap_unknown:
             return ':obj:`%s`' % link
+        return link
 
     def _split_and_apply_re(s, pattern):
         """
@@ -142,7 +143,8 @@ def _split_and_apply_re(s, pattern):
                     results.append(tok)
                 else:
                     res = make_xref(
-                        tok, xref_aliases, xref_ignore)
+                        tok, xref_aliases, xref_ignore, wrap_unknown
+                    )
                     # Opening brackets immediately after a role is
                     # bad markup. Detect that and add backslash.
                     # :role:`type`( to :role:`type`\(