diff options
author | Ross Barnowski <rossbar@berkeley.edu> | 2020-08-05 06:00:49 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-08-05 09:00:49 -0400 |
commit | 7bee33a6841666c8410366053213ce61e8652bd2 (patch) | |
tree | 894404a147e4ff91c403573112f621f6893c4c8e | |
parent | 4e86e815a855502eef1a796a5d3f217b08aaa79f (diff) | |
download | numpydoc-7bee33a6841666c8410366053213ce61e8652bd2.tar.gz |
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.
-rw-r--r-- | doc/install.rst | 9 | ||||
-rw-r--r-- | numpydoc/tests/test_xref.py | 64 | ||||
-rw-r--r-- | numpydoc/xref.py | 6 |
3 files changed, 31 insertions, 48 deletions
diff --git a/doc/install.rst b/doc/install.rst index ba799e3..46b26f8 100644 --- a/doc/install.rst +++ b/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 diff --git a/numpydoc/tests/test_xref.py b/numpydoc/tests/test_xref.py index 31dfacd..5d16919 100644 --- a/numpydoc/tests/test_xref.py +++ b/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 @@ data = r""" (..., :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 @@ str or pathlib.Path {'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 @@ spmatrix (format: ``csr``, ``bsr``, ``dia`` or coo``) :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'} diff --git a/numpydoc/xref.py b/numpydoc/xref.py index a4ceaf9..7c6612e 100644 --- a/numpydoc/xref.py +++ b/numpydoc/xref.py @@ -95,7 +95,9 @@ DEFAULT_LINKS = { 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: |