Add cross-reference links to parameter types

Tokens of the type description that are determined to be "link-worthy"
are enclosed in a new role called `xref_param_type`. This role when
when processed adds a `pending_xref` node to the DOM. If these types
cross-references are not resolved when the build ends, sphinx does
not complain. This forgives errors made when deciding whether tokens
are "link-worthy". And provided text from the type description is not
lost in the processing, the only unwanted outcome is a type link (due
to coincidence) when none was desired.

Added two options:

   1. numpydoc_xref_param_type
   2. numpydoc_xref_aliases

Author: has2k1

doc/install.rst

@@ -42,6 +42,44 @@ numpydoc_use_blockqutoes : bool
   Until version 0.8, parameter definitions were shown as blockquotes, rather
   than in a definition list.  If your styling requires blockquotes, switch
   this config option to True.  This option will be removed in version 0.10.
+numpydoc_xref_param_type : bool
+  Whether to create cross-references for the parameter types in the
+  ``Parameters``, ``Other Parameters``, ``Returns`` and ``Yields``
+  sections of the docstring.
+  ``True`` by default.
+numpydoc_xref_aliases : dict
+  Mappings to fully qualified paths (or correct ReST references) for the
+  aliases/shortcuts used when specifying the types of parameters.
+  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),
+      }
+
+  A useful ``dict`` may look like the following::
+
+      numpydoc_xref_aliases = {
+          # python
+          'sequence': ':term:`python:sequence`',
+          'iterable': ':term:`python:iterable`',
+          'string': 'str',
+          # numpy
+          'array': '~numpy.array',
+          'dtype': '~numpy.dtype',
+          'ndarray': '~numpy.ndarray',
+          'matrix': 'numpy.matrix',
+          'array-like': ':term:`numpy:array_like`',
+          'array_like': ':term:`numpy:array_like`',
+      }
+
+   This option depends on the ``numpydoc_xref_param_type`` option
+   being ``True``.
+
 numpydoc_edit_link : bool
   .. deprecated:: edit your HTML template instead
 

numpydoc/docscrape_sphinx.py

@@ -14,6 +14,7 @@
 from sphinx.jinja2glue import BuiltinTemplateLoader
 
 from .docscrape import NumpyDocString, FunctionDoc, ClassDoc
+from .xref import make_xref_param_type
 
 if sys.version_info[0] >= 3:
     sixu = lambda s: s
@@ -33,6 +34,8 @@ def load_config(self, config):
         self.use_plots = config.get('use_plots', False)
         self.use_blockquotes = config.get('use_blockquotes', False)
         self.class_members_toctree = config.get('class_members_toctree', True)
+        self.xref_param_type = config.get('xref_param_type', False)
+        self.xref_aliases = config.get('xref_aliases', dict())
         self.template = config.get('template', None)
         if self.template is None:
             template_dirs = [os.path.join(os.path.dirname(__file__), 'templates')]
@@ -80,6 +83,10 @@ def _str_returns(self, name='Returns'):
             out += ['']
             for param, param_type, desc in self[name]:
                 if param_type:
+                    if self.xref_param_type:
+                        param_type = make_xref_param_type(
+                            param_type,
+                            self.xref_aliases)
                     out += self._str_indent([typed_fmt % (param.strip(),
                                                           param_type)])
                 else:
@@ -197,6 +204,10 @@ def _str_param_list(self, name, fake_autosummary=False):
                                                           fake_autosummary)
 
                 if param_type:
+                    if self.xref_param_type:
+                        param_type = make_xref_param_type(
+                            param_type,
+                            self.xref_aliases)
                     out += self._str_indent(['%s : %s' % (display_param,
                                                           param_type)])
                 else:

numpydoc/numpydoc.py

@@ -24,6 +24,7 @@
 import sphinx
 import inspect
 import collections
+from sphinx import addnodes
 
 if sphinx.__version__ < '1.0.1':
     raise RuntimeError("Sphinx 1.0.1 or newer is required")
@@ -76,7 +77,10 @@ def mangle_docstrings(app, what, name, obj, options, lines):
            'show_class_members': app.config.numpydoc_show_class_members,
            'show_inherited_class_members':
            app.config.numpydoc_show_inherited_class_members,
-           'class_members_toctree': app.config.numpydoc_class_members_toctree}
+           'class_members_toctree': app.config.numpydoc_class_members_toctree,
+           'xref_param_type': app.config.numpydoc_xref_param_type,
+           'xref_aliases': app.config.numpydoc_xref_aliases,
+           }
 
     u_NL = sixu('\n')
     if what == 'module':
@@ -137,6 +141,7 @@ def setup(app, get_doc_object_=get_doc_object):
     global get_doc_object
     get_doc_object = get_doc_object_
 
+    app.add_role('xref_param_type', xref_param_type_role)
     app.connect('autodoc-process-docstring', mangle_docstrings)
     app.connect('autodoc-process-signature', mangle_signature)
     app.add_config_value('numpydoc_edit_link', None, False)
@@ -146,6 +151,8 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value('numpydoc_show_inherited_class_members', True, True)
     app.add_config_value('numpydoc_class_members_toctree', True, True)
     app.add_config_value('numpydoc_citation_re', '[a-z0-9_.-]+', True)
+    app.add_config_value('numpydoc_xref_param_type', True, True)
+    app.add_config_value('numpydoc_xref_aliases', dict(), True)
 
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)
@@ -283,3 +290,23 @@ def run(self):
             return base_directive.run(self)
 
     return directive
+
+
+def xref_param_type_role(role, rawtext, text, lineno, inliner):
+    """
+    Add a pendinding_xref for the param_type of a field list
+    """
+    if text.startswith(('~', '.')):
+        prefix, target = text[0], text[1:]
+        if prefix == '.':
+            text = text[1:]
+        elif prefix == '~':
+            text = text.split('.')[-1]
+    else:
+        target = text
+
+    contnode = addnodes.literal_emphasis(text, text)
+    node = addnodes.pending_xref('', refdomain='py', refexplicit=False,
+                                 reftype='obj', reftarget=target)
+    node += contnode
+    return [node], []

numpydoc/tests/test_docscrape.py

@@ -1199,6 +1199,82 @@ def test_templated_sections():
     """)
 
 
+xref_doc_txt = """
+Test xref in Parameters, Other Parameters and Returns
+
+Parameters
+----------
+p1 : int
+    Integer value
+
+p2 : float, optional
+    Integer value
+
+Other Parameters
+----------------
+p3 : list[int]
+    List of integers
+p4 : :class:`pandas.DataFrame`
+    A dataframe
+p5 : sequence of int
+    A sequence
+
+Returns
+-------
+out : array
+    Numerical return value
+"""
+
+
+xref_doc_txt_expected = """
+Test xref in Parameters, Other Parameters and Returns
+
+
+:Parameters:
+
+    p1 : :xref_param_type:`int`
+        Integer value
+
+    p2 : :xref_param_type:`float`, optional
+        Integer value
+
+:Returns:
+
+    out : :xref_param_type:`~numpy.array`
+        Numerical return value
+
+
+:Other Parameters:
+
+    p3 : :xref_param_type:`list`[:xref_param_type:`int`]
+        List of integers
+
+    p4 : :class:`pandas.DataFrame`
+        A dataframe
+
+    p5 : :term:`python:sequence` of :xref_param_type:`int`
+        A sequence
+"""
+
+
+def test_xref():
+    xref_aliases = {
+        'sequence': ':term:`python:sequence`',
+        'iterable': ':term:`python:iterable`',
+        'array': '~numpy.array',
+    }
+
+    doc = SphinxDocString(
+        xref_doc_txt,
+        config=dict(
+            xref_param_type=True,
+            xref_aliases=xref_aliases
+        )
+    )
+
+    line_by_line_compare(str(doc), xref_doc_txt_expected)
+
+
 if __name__ == "__main__":
     import nose
     nose.run()

numpydoc/tests/test_xref.py

@@ -0,0 +1,109 @@
+# -*- encoding:utf-8 -*-
+from __future__ import division, absolute_import, print_function
+
+from numpydoc.xref import make_xref_param_type
+
+xref_aliases = {
+    # python
+    'sequence': ':term:`python:sequence`',
+    'iterable': ':term:`python:iterable`',
+    'string': 'str',
+    # numpy
+    'array': '~numpy.array',
+    'dtype': 'numpy.dtype',
+    'ndarray': '~numpy.ndarray',
+    'matrix': 'numpy.matrix',
+    'array-like': ':term:`numpy:array_like`',
+    'array_like': ':term:`numpy:array_like`',
+}
+
+# Comes mainly from numpy
+data = """
+(...) array_like, float, optional
+(...) :term:`numpy:array_like`, :xref_param_type:`float`, optional
+
+(2,) ndarray
+(2,) :xref_param_type:`~numpy.ndarray`
+
+(...,M,N) array_like
+(...,M,N) :term:`numpy:array_like`
+
+(float, float), optional
+(:xref_param_type:`float`, :xref_param_type:`float`), optional
+
+1-D array or sequence
+1-D :xref_param_type:`~numpy.array` or :term:`python:sequence`
+
+array of str or unicode-like
+:xref_param_type:`~numpy.array` of :xref_param_type:`str` or unicode-like
+
+array_like of float
+:term:`numpy:array_like` of :xref_param_type:`float`
+
+bool or callable
+:xref_param_type:`bool` or :xref_param_type:`callable`
+
+int in [0, 255]
+:xref_param_type:`int` in [0, 255]
+
+int or None, optional
+:xref_param_type:`int` or :xref_param_type:`None`, optional
+
+list of str or array_like
+:xref_param_type:`list` of :xref_param_type:`str` or :term:`numpy:array_like`
+
+sequence of array_like
+:term:`python:sequence` of :term:`numpy:array_like`
+
+str or pathlib.Path
+:xref_param_type:`str` or :xref_param_type:`pathlib.Path`
+
+{'', string}, optional
+{'', :xref_param_type:`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'}
+{:xref_param_type:`False`, :xref_param_type:`True`, 'greedy', 'optimal'}
+
+{{'begin', 1}, {'end', 0}}, {string, int}
+{{'begin', 1}, {'end', 0}}, {string, :xref_param_type:`int`}
+
+callable f'(x,*args)
+:xref_param_type:`callable` f'(x,*args)
+
+callable ``fhess(x, *args)``, optional
+:xref_param_type:`callable` ``fhess(x, *args)``, optional
+
+spmatrix (format: ``csr``, ``bsr``, ``dia`` or coo``)
+:xref_param_type:`spmatrix` (format: ``csr``, ``bsr``, ``dia`` or coo``)
+
+list(int)
+:xref_param_type:`list`(:xref_param_type:`int`)
+
+list[int]
+:xref_param_type:`list`[:xref_param_type:`int`]
+
+dict(str, int)
+:xref_param_type:`dict`(:xref_param_type:`str`, :xref_param_type:`int`)
+
+dict[str,  int]
+:xref_param_type:`dict`[:xref_param_type:`str`,  :xref_param_type:`int`]
+
+tuple(float, float)
+:xref_param_type:`tuple`(:xref_param_type:`float`, :xref_param_type:`float`)
+
+dict[tuple(str, str), int]
+:xref_param_type:`dict`[:xref_param_type:`tuple`(:xref_param_type:`str`, :xref_param_type:`str`), :xref_param_type:`int`]
+"""  # noqa: E501
+
+
+def test_make_xref_param_type():
+    for s in data.strip().split('\n\n'):
+        param_type, expected_result = s.split('\n')
+        result = make_xref_param_type(param_type, xref_aliases)
+        assert result == expected_result