MAINT: Updates related to xref (#292)

* TST: use default links in xref test.

Switch to numpydoc's default link mapping for test_xref instead of
the custom (less comprehensive) link mapping.

* DOC: rm statements about xref_alias dict.

Default aliases are not an empty dict, nor are they dependent
on intersphinx.

* DOC: Update make_xref docstring.

Author: rossbar

doc/install.rst

@@ -63,15 +63,6 @@ numpydoc_xref_aliases : dict
   aliases/shortcuts used when specifying the types of parameters.
   The keys should not have any spaces. Together with the ``intersphinx``
   extension, you can map to links in any documentation.
-  The default is an empty ``dict``.
-
-  If you have the following ``intersphinx`` namespace configuration::
-
-      intersphinx_mapping = {
-          'python': ('https://docs.python.org/3/', None),
-          'numpy': ('https://docs.scipy.org/doc/numpy', None),
-          ...
-      }
 
   The default ``numpydoc_xref_aliases`` will supply some common ``Python``
   standard library and ``NumPy`` names for you. Then for your module, a useful

numpydoc/tests/test_xref.py

@@ -1,25 +1,15 @@
 # -*- encoding:utf-8 -*-
 import pytest
-from numpydoc.xref import make_xref
-
-xref_aliases = {
-    # python
-    'sequence': ':term:`python:sequence`',
-    'iterable': ':term:`python:iterable`',
-    'string': 'str',
-    # numpy
-    'array': 'numpy.ndarray',
-    'dtype': 'numpy.dtype',
-    'ndarray': 'numpy.ndarray',
-    'matrix': 'numpy.matrix',
-    'array-like': ':term:`numpy:array_like`',
-    'array_like': ':term:`numpy:array_like`',
-}
+from numpydoc.xref import make_xref, DEFAULT_LINKS
+
+# Use the default numpydoc link mapping
+xref_aliases = DEFAULT_LINKS
+
 
 # Comes mainly from numpy
 data = r"""
 (...) array_like, float, optional
-(...) :term:`numpy:array_like`, :obj:`float`, optional
+(...) :term:`numpy:array_like`, :class:`python:float`, optional
 
 (2,) ndarray
 (2,) :obj:`ndarray <numpy.ndarray>`
@@ -31,37 +21,37 @@
 (..., :obj:`M`, :obj:`N`) :term:`numpy:array_like`
 
 (float, float), optional
-(:obj:`float`, :obj:`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 :obj:`str` or unicode-like
+:obj:`array <numpy.ndarray>` of :class:`python:str` or unicode-like
 
 array_like of float
-:term:`numpy:array_like` of :obj:`float`
+:term:`numpy:array_like` of :class:`python:float`
 
 bool or callable
-:obj:`bool` or :obj:`callable`
+:ref:`bool <python:bltin-boolean-values>` or :func:`python:callable`
 
 int in [0, 255]
-:obj:`int` in [0, 255]
+:class:`python:int` in [0, 255]
 
 int or None, optional
-:obj:`int` or :obj:`None`, optional
+:class:`python:int` or :data:`python:None`, optional
 
 list of str or array_like
-:obj:`list` of :obj:`str` or :term:`numpy: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
-:obj:`str` or :obj:`pathlib.Path`
+:class:`python:str` or :obj:`pathlib.Path`
 
 {'', string}, optional
-{'', :obj:`string <str>`}, optional
+{'', :class:`python:str`}, optional
 
 {'C', 'F', 'A', or 'K'}, optional
 {'C', 'F', 'A', or 'K'}, optional
@@ -70,16 +60,16 @@
 {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
 
 {False, True, 'greedy', 'optimal'}
-{:obj:`False`, :obj:`True`, 'greedy', 'optimal'}
+{:data:`python:False`, :data:`python:True`, 'greedy', 'optimal'}
 
 {{'begin', 1}, {'end', 0}}, {string, int}
-{{'begin', 1}, {'end', 0}}, {:obj:`string <str>`, :obj:`int`}
+{{'begin', 1}, {'end', 0}}, {:class:`python:str`, :class:`python:int`}
 
 callable f'(x,*args)
-:obj:`callable` f'(x,*args)
+:func:`python:callable` f'(x,*args)
 
 callable ``fhess(x, *args)``, optional
-:obj:`callable` ``fhess(x, *args)``, optional
+:func:`python:callable` ``fhess(x, *args)``, optional
 
 spmatrix (format: ``csr``, ``bsr``, ``dia`` or coo``)
 :obj:`spmatrix` (format: ``csr``, ``bsr``, ``dia`` or coo``)
@@ -88,28 +78,28 @@
 :ref:`strftime <strftime-strptime-behavior>`
 
 callable or :ref:`strftime <strftime-strptime-behavior>`
-:obj:`callable` or :ref:`strftime <strftime-strptime-behavior>`
+:func:`python:callable` or :ref:`strftime <strftime-strptime-behavior>`
 
 callable or :ref:`strftime behavior <strftime-strptime-behavior>`
-:obj:`callable` or :ref:`strftime behavior <strftime-strptime-behavior>`
+:func:`python:callable` or :ref:`strftime behavior <strftime-strptime-behavior>`
 
 list(int)
-:obj:`list`\(:obj:`int`)
+:class:`python:list`\(:class:`python:int`)
 
 list[int]
-:obj:`list`\[:obj:`int`]
+:class:`python:list`\[:class:`python:int`]
 
 dict(str, int)
-:obj:`dict`\(:obj:`str`, :obj:`int`)
+:class:`python:dict`\(:class:`python:str`, :class:`python:int`)
 
 dict[str,  int]
-:obj:`dict`\[:obj:`str`,  :obj:`int`]
+:class:`python:dict`\[:class:`python:str`,  :class:`python:int`]
 
 tuple(float, float)
-:obj:`tuple`\(:obj:`float`, :obj:`float`)
+:class:`python:tuple`\(:class:`python:float`, :class:`python:float`)
 
 dict[tuple(str, str), int]
-:obj:`dict`\[:obj:`tuple`\(:obj:`str`, :obj:`str`), :obj:`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'}

numpydoc/xref.py

@@ -95,7 +95,9 @@
 
 
 def make_xref(param_type, xref_aliases, xref_ignore):
-    """Enclose str in a :obj: role.
+    """Parse and apply appropriate sphinx role(s) to `param_type`.
+
+    The :obj: role is the default.
 
     Parameters
     ----------
@@ -110,7 +112,7 @@ def make_xref(param_type, xref_aliases, xref_ignore):
     Returns
     -------
     out : str
-        Text with parts that may be wrapped in a
+        Text with fully-qualified names and terms that may be wrapped in a
         ``:obj:`` role.
     """
     if param_type in xref_aliases: