diff options
author | Ross Barnowski <rossbar@berkeley.edu> | 2020-08-17 14:49:08 -0700 |
---|---|---|
committer | Ross Barnowski <rossbar@berkeley.edu> | 2020-08-17 15:30:03 -0700 |
commit | e8f237ec2b5ace76da2e0bbf62a7cffb1a637422 (patch) | |
tree | 978b33034ac11ee3bf3fbd7f948f092bb9547319 | |
parent | 676a8d4c1627e92052c2f3a5e2bde558e9a59f96 (diff) | |
download | numpydoc-e8f237ec2b5ace76da2e0bbf62a7cffb1a637422.tar.gz |
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.
-rw-r--r-- | numpydoc/tests/test_xref.py | 102 | ||||
-rw-r--r-- | numpydoc/xref.py | 8 |
2 files changed, 107 insertions, 3 deletions
diff --git a/numpydoc/tests/test_xref.py b/numpydoc/tests/test_xref.py index 5d16919..3ed0d6f 100644 --- a/numpydoc/tests/test_xref.py +++ b/numpydoc/tests/test_xref.py @@ -102,6 +102,101 @@ dict[tuple(str, str), int] :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 @@ xref_ignore = {'or', 'in', 'of', 'default', 'optional'} ) 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 diff --git a/numpydoc/xref.py b/numpydoc/xref.py index 7c6612e..8cb3761 100644 --- a/numpydoc/xref.py +++ b/numpydoc/xref.py @@ -94,7 +94,7 @@ DEFAULT_LINKS = { } -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 make_xref(param_type, xref_aliases, xref_ignore): 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`\( |