diff options
author | Eric Larson <larson.eric.d@gmail.com> | 2019-01-14 12:30:51 -0500 |
---|---|---|
committer | Eric Larson <larson.eric.d@gmail.com> | 2019-04-17 21:22:03 -0400 |
commit | 807f4e02cdb95e7e4c564b440629aeda5832299a (patch) | |
tree | 6e288b19753ab46ec922ab743d3db2d6745b76cf | |
parent | 477ff10470784baa344229fde5880e4e2bffb545 (diff) | |
download | numpydoc-807f4e02cdb95e7e4c564b440629aeda5832299a.tar.gz |
FIX: Opt-in, test, uniform styling, css
-rw-r--r-- | doc/install.rst | 10 | ||||
-rw-r--r-- | numpydoc/docscrape_sphinx.py | 8 | ||||
-rw-r--r-- | numpydoc/numpydoc.py | 2 | ||||
-rw-r--r-- | numpydoc/tests/test_docscrape.py | 18 | ||||
-rw-r--r-- | numpydoc/tests/test_xref.py | 5 | ||||
-rw-r--r-- | numpydoc/xref.py | 20 |
6 files changed, 37 insertions, 26 deletions
diff --git a/doc/install.rst b/doc/install.rst index c6d6209..18e22bb 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -51,7 +51,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. @@ -84,7 +90,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 @@ -93,7 +98,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 diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 942c78f..a77390b 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -225,14 +225,16 @@ class SphinxDocString(NumpyDocString): parts.append(display_param) param_type = param.type 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) - parts.append(param_type) - out += self._str_indent([' : '.join(parts)]) - +(??) out += self._str_indent(['%s : %s' % (display_param, +(??) param.type)]) +(??) else: +(??) out += self._str_indent([display_param]) if desc and self.use_blockquotes: out += [''] elif not desc: diff --git a/numpydoc/numpydoc.py b/numpydoc/numpydoc.py index b8e993f..fc713a9 100644 --- a/numpydoc/numpydoc.py +++ b/numpydoc/numpydoc.py @@ -236,7 +236,7 @@ def setup(app, get_doc_object_=get_doc_object): 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_attributes_as_param_list', True, 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) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 2f5a688..8bb05d7 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -387,7 +387,9 @@ 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)), str([[x, y] for x, y in zip(a, b) if x != y]) + assert len(a) == len(b) + for ii, (aa, bb) in enumerate(zip(a, b)): + assert aa == bb def test_str(): @@ -1450,33 +1452,33 @@ out : array """ -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 """ diff --git a/numpydoc/tests/test_xref.py b/numpydoc/tests/test_xref.py index 8786d4b..0595026 100644 --- a/numpydoc/tests/test_xref.py +++ b/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 @@ xref_aliases = { } # 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 diff --git a/numpydoc/xref.py b/numpydoc/xref.py index 5804a7c..11c3fbe 100644 --- a/numpydoc/xref.py +++ b/numpydoc/xref.py @@ -66,8 +66,8 @@ CONTAINER_CHARS = set('[](){}') 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], [] |