FIX: Opt-in, test, uniform styling, css

Author: larsoner

doc/install.rst

@@ -46,7 +46,13 @@ 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.
+  ``False`` by default.
+
+  .. note:: Depending on the link types, the CSS styles might be different.
+            consider overridding e.g. ``span.classifier a span.xref`` and
+            ``span.classifier a code.docutils.literal.notranslate``
+            CSS classes to achieve a uniform appearance.
+
 numpydoc_xref_aliases : dict
   Mappings to fully qualified paths (or correct ReST references) for the
   aliases/shortcuts used when specifying the types of parameters.
@@ -79,7 +85,6 @@ numpydoc_xref_aliases : dict
 
    This option depends on the ``numpydoc_xref_param_type`` option
    being ``True``.
-
 numpydoc_xref_ignore : set
     Words not to cross-reference. Most likely, these are common words
     used in parameter type descriptions that may be confused for
@@ -88,7 +93,6 @@ numpydoc_xref_ignore : set
         numpydoc_xref_ignore = {'type', 'optional', 'default'}
 
     The default is an empty set.
-
 numpydoc_edit_link : bool
   .. deprecated:: edit your HTML template instead
 

numpydoc/docscrape_sphinx.py

@@ -82,14 +82,15 @@ def _str_returns(self, name='Returns'):
             out += self._str_field_list(name)
             out += ['']
             for param in self[name]:
-                if param.type:
+                param_type = param.type
+                if param_type:
                     if self.xref_param_type:
-                        param.type = make_xref_param_type(
-                            param.type,
+                        param_type = make_xref_param_type(
+                            param_type,
                             self.xref_aliases,
                             self.xref_ignore)
-                    out += self._str_indent([typed_fmt % (param.strip(),
-                                                          param.type)])
+                    out += self._str_indent([typed_fmt % (param.name.strip(),
+                                                          param_type)])
                 else:
                     out += self._str_indent([untyped_fmt % param.name.strip()])
                 if not param.desc:
@@ -220,13 +221,14 @@ def _str_param_list(self, name, fake_autosummary=False):
                                                           fake_autosummary)
 
                 if param.type:
+                    param_type = param.type
                     if self.xref_param_type:
                         param_type = make_xref_param_type(
                             param_type,
                             self.xref_aliases,
                             self.xref_ignore)
                     out += self._str_indent(['%s : %s' % (display_param,
-                                                          param.type)])
+                                                          param_type)])
                 else:
                     out += self._str_indent([display_param])
                 if desc and self.use_blockquotes:

numpydoc/numpydoc.py

@@ -210,7 +210,7 @@ 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_param_type', False, True)
     app.add_config_value('numpydoc_xref_aliases', dict(), True)
     app.add_config_value('numpydoc_xref_ignore', set(), True)
 

numpydoc/tests/test_docscrape.py

@@ -335,7 +335,8 @@ def line_by_line_compare(a, b):
     b = textwrap.dedent(b)
     a = [l.rstrip() for l in _strip_blank_lines(a).split('\n')]
     b = [l.rstrip() for l in _strip_blank_lines(b).split('\n')]
-    assert all(x == y for x, y in zip(a, b))
+    for ii, (aa, bb) in enumerate(zip(a, b)):
+        assert aa == bb
 
 
 def test_str():
@@ -1295,33 +1296,33 @@ def test_args_and_kwargs():
 """
 
 
-xref_doc_txt_expected = """
+xref_doc_txt_expected = r"""
 Test xref in Parameters, Other Parameters and Returns
 
 
 :Parameters:
 
-    p1 : :xref_param_type:`int`
+    **p1** : :xref_param_type:`int`
         Integer value
 
-    p2 : :xref_param_type:`float`, optional
+    **p2** : :xref_param_type:`float`, optional
         Integer value
 
 :Returns:
 
-    out : :xref_param_type:`array <numpy.ndarray>`
+    **out** : :xref_param_type:`array <numpy.ndarray>`
         Numerical return value
 
 
 :Other Parameters:
 
-    p3 : :xref_param_type:`list`\[:xref_param_type:`int`]
+    **p3** : :xref_param_type:`list`\[:xref_param_type:`int`]
         List of integers
 
-    p4 : :class:`pandas.DataFrame`
+    **p4** : :class:`pandas.DataFrame`
         A dataframe
 
-    p5 : :term:`python:sequence` of :xref_param_type:`int`
+    **p5** : :term:`python:sequence` of :xref_param_type:`int`
         A sequence
 """
 

numpydoc/tests/test_xref.py

@@ -1,7 +1,6 @@
 # -*- encoding:utf-8 -*-
 from __future__ import division, absolute_import, print_function
 
-from nose.tools import assert_equal
 from numpydoc.xref import make_xref_param_type
 
 xref_aliases = {
@@ -19,7 +18,7 @@
 }
 
 # Comes mainly from numpy
-data = """
+data = r"""
 (...) array_like, float, optional
 (...) :term:`numpy:array_like`, :xref_param_type:`float`, optional
 
@@ -125,4 +124,4 @@ def test_make_xref_param_type():
             xref_aliases,
             xref_ignore
         )
-        assert_equal(result, expected_result)
+        assert result == expected_result

numpydoc/xref.py

@@ -66,8 +66,8 @@
 
 
 def make_xref_param_type(param_type, xref_aliases, xref_ignore):
-    """
-    Enclose str in a role that creates a cross-reference
+    """Enclose str in a role that creates a cross-reference.
+
     The role ``xref_param_type`` *may be* added to any token
     that looks like type information and no other. The
     function tries to be clever and catch type information
@@ -165,21 +165,25 @@ def xref_param_type_role(role, rawtext, text, lineno, inliner,
     Add a pending_xref for the param_type of a field list
     """
     has_title, title, target = split_explicit_title(text)
+    env = inliner.document.settings.env
     if has_title:
         target = target.lstrip('~')
     else:
         if target.startswith(('~', '.')):
             prefix, target = target[0], target[1:]
             if prefix == '.':
-                env = inliner.document.settings.env
                 modname = env.ref_context.get('py:module')
                 target = target[1:]
                 target = '%s.%s' % (modname, target)
             elif prefix == '~':
                 title = target.split('.')[-1]
 
-    contnode = nodes.Text(title, title)
-    node = addnodes.pending_xref('', refdomain='py', refexplicit=False,
-                                 reftype='class', reftarget=target)
-    node += contnode
-    return [node], []
+    domain = 'py'
+    contnode = nodes.literal(title, title)
+    refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
+                                    reftype='class', reftarget=target)
+    refnode += contnode
+    # attach information about the current scope
+    if env:
+        env.get_domain(domain).process_field_xref(refnode)
+    return [refnode], []