ENH: Just use obj

Author: larsoner

.gitignore

@@ -8,3 +8,4 @@
 *.swo
 build
 dist
+doc/_build

doc/Makefile

@@ -15,7 +15,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -nWT --keep-going -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 

doc/conf.py

@@ -82,6 +82,8 @@
 release = numpydoc.__version__
 version = re.sub(r'(\d+\.\d+)\.\d+(.*)', r'\1\2', numpydoc.__version__)
 version = re.sub(r'(\.dev\d+).*?$', r'\1', version)
+numpydoc_xref_param_type = True
+numpydoc_xref_ignore = {'optional'}
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -269,5 +271,6 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('http://docs.python.org/', None),
-    'scikitlearn': ('http://scikit-learn.org/stable/', None),
+    'numpy': ('https://www.numpy.org/devdocs', None),
+    'sklearn': ('http://scikit-learn.org/stable/', None),
 }

doc/example.py

@@ -78,10 +78,10 @@ def foo(var1, var2, long_var_name='hi'):
 
     See Also
     --------
-    otherfunc : relationship (optional)
-    newfunc : Relationship (optional), which could be fairly long, in which
-              case the line wraps here.
-    thirdfunc, fourthfunc, fifthfunc
+    numpy.array : relationship (optional)
+    numpy.ndarray : Relationship (optional), which could be fairly long, in
+                    which case the line wraps here.
+    numpy.dot, numpy.linalg.norm, numpy.eye
 
     Notes
     -----

doc/install.rst

@@ -65,26 +65,21 @@ numpydoc_xref_aliases : dict
       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::
+  The default ``numpydoc_xref_aliases`` will supply some common ``Python``
+  standard library and ``NumPy`` names for you. Then for your module, a useful
+  ``dict`` may look like the following (e.g., if you were documenting
+  :mod:`sklearn.model_selection`)::
 
       numpydoc_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`',
+          'LeaveOneOut': 'sklearn.model_selection.LeaveOneOut',
+          ...
       }
 
-   This option depends on the ``numpydoc_xref_param_type`` option
-   being ``True``.
+  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

numpydoc/docscrape_sphinx.py

@@ -17,7 +17,7 @@
 from sphinx.jinja2glue import BuiltinTemplateLoader
 
 from .docscrape import NumpyDocString, FunctionDoc, ClassDoc
-from .xref import make_xref_param_type
+from .xref import make_xref
 
 if sys.version_info[0] >= 3:
     sixu = lambda s: s
@@ -84,7 +84,7 @@ def _str_returns(self, name='Returns'):
             for param in self[name]:
                 param_type = param.type
                 if param_type and self.xref_param_type:
-                    param_type = make_xref_param_type(
+                    param_type = make_xref(
                         param_type,
                         self.xref_aliases,
                         self.xref_ignore)
@@ -226,7 +226,7 @@ def _str_param_list(self, name, fake_autosummary=False):
                 if param_type:
                     param_type = param.type
                     if self.xref_param_type:
-                        param_type = make_xref_param_type(
+                        param_type = make_xref(
                             param_type,
                             self.xref_aliases,
                             self.xref_ignore)

numpydoc/numpydoc.py

@@ -37,7 +37,7 @@
     raise RuntimeError("Sphinx 1.0.1 or newer is required")
 
 from .docscrape_sphinx import get_doc_object
-from .xref import xref_param_type_role
+from .xref import DEFAULT_LINKS
 from . import __version__
 
 if sys.version_info[0] >= 3:
@@ -221,7 +221,7 @@ def setup(app, get_doc_object_=get_doc_object):
 
     app.setup_extension('sphinx.ext.autosummary')
 
-    app.add_role('xref_param_type', xref_param_type_role)
+    app.connect('builder-inited', update_config)
     app.connect('autodoc-process-docstring', mangle_docstrings)
     app.connect('autodoc-process-signature', mangle_signature)
     app.connect('doctree-read', relabel_references)
@@ -245,6 +245,14 @@ def setup(app, get_doc_object_=get_doc_object):
                 'parallel_read_safe': True}
     return metadata
 
+
+def update_config(app):
+    """Update the configuration with default values."""
+    for key, value in DEFAULT_LINKS.items():
+        if key not in app.config.numpydoc_xref_aliases:
+            app.config.numpydoc_xref_aliases[key] = value
+
+
 # ------------------------------------------------------------------------------
 # Docstring-mangling domains
 # ------------------------------------------------------------------------------

numpydoc/tests/test_docscrape.py

@@ -1,13 +1,15 @@
 # -*- encoding:utf-8 -*-
 from __future__ import division, absolute_import, print_function
 
+from collections import namedtuple
 import re
 import sys
 import textwrap
 import warnings
 
 import jinja2
 
+from numpydoc.numpydoc import update_config
 from numpydoc.docscrape import (
     NumpyDocString,
     FunctionDoc,
@@ -1389,7 +1391,7 @@ def test_autoclass():
     List of integers
 p4 : :class:`pandas.DataFrame`
     A dataframe
-p5 : sequence of int
+p5 : sequence of `int`
     A sequence
 
 Returns
@@ -1405,37 +1407,39 @@ def test_autoclass():
 
 :Parameters:
 
-    **p1** : :xref_param_type:`int`
+    **p1** : :class:`python:int`
         Integer value
 
-    **p2** : :xref_param_type:`float`, optional
+    **p2** : :class:`python:float`, optional
         Integer value
 
 :Returns:
 
-    **out** : :xref_param_type:`array <numpy.ndarray>`
+    **out** : :obj:`array <numpy.ndarray>`
         Numerical return value
 
 
 :Other Parameters:
 
-    **p3** : :xref_param_type:`list`\[:xref_param_type:`int`]
+    **p3** : :class:`python:list`\[:class:`python:int`]
         List of integers
 
     **p4** : :class:`pandas.DataFrame`
         A dataframe
 
-    **p5** : :term:`python:sequence` of :xref_param_type:`int`
+    **p5** : :obj:`python:sequence` of `int`
         A sequence
 """
 
 
 def test_xref():
     xref_aliases = {
-        'sequence': ':term:`python:sequence`',
-        'iterable': ':term:`python:iterable`',
-        'array': 'numpy.ndarray',
+        'sequence': ':obj:`python:sequence`',
     }
+    config = namedtuple('numpydoc_xref_aliases',
+                        'numpydoc_xref_aliases')(xref_aliases)
+    app = namedtuple('config', 'config')(config)
+    update_config(app)
 
     xref_ignore = {'of', 'default', 'optional'}
 

numpydoc/tests/test_xref.py

@@ -1,7 +1,7 @@
 # -*- encoding:utf-8 -*-
 from __future__ import division, absolute_import, print_function
 
-from numpydoc.xref import make_xref_param_type
+from numpydoc.xref import make_xref
 
 xref_aliases = {
     # python
@@ -20,49 +20,49 @@
 # Comes mainly from numpy
 data = r"""
 (...) array_like, float, optional
-(...) :term:`numpy:array_like`, :xref_param_type:`float`, optional
+(...) :term:`numpy:array_like`, :obj:`float`, optional
 
 (2,) ndarray
-(2,) :xref_param_type:`ndarray <numpy.ndarray>`
+(2,) :obj:`ndarray <numpy.ndarray>`
 
 (...,M,N) array_like
 (...,M,N) :term:`numpy:array_like`
 
 (..., M, N) array_like
-(..., :xref_param_type:`M`, :xref_param_type:`N`) :term:`numpy:array_like`
+(..., :obj:`M`, :obj:`N`) :term:`numpy:array_like`
 
 (float, float), optional
-(:xref_param_type:`float`, :xref_param_type:`float`), optional
+(:obj:`float`, :obj:`float`), optional
 
 1-D array or sequence
-1-D :xref_param_type:`array <numpy.ndarray>` or :term:`python:sequence`
+1-D :obj:`array <numpy.ndarray>` or :term:`python:sequence`
 
 array of str or unicode-like
-:xref_param_type:`array <numpy.ndarray>` of :xref_param_type:`str` or unicode-like
+:obj:`array <numpy.ndarray>` of :obj:`str` or unicode-like
 
 array_like of float
-:term:`numpy:array_like` of :xref_param_type:`float`
+:term:`numpy:array_like` of :obj:`float`
 
 bool or callable
-:xref_param_type:`bool` or :xref_param_type:`callable`
+:obj:`bool` or :obj:`callable`
 
 int in [0, 255]
-:xref_param_type:`int` in [0, 255]
+:obj:`int` in [0, 255]
 
 int or None, optional
-:xref_param_type:`int` or :xref_param_type:`None`, optional
+:obj:`int` or :obj:`None`, optional
 
 list of str or array_like
-:xref_param_type:`list` of :xref_param_type:`str` or :term:`numpy:array_like`
+:obj:`list` of :obj:`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`
+:obj:`str` or :obj:`pathlib.Path`
 
 {'', string}, optional
-{'', :xref_param_type:`string <str>`}, optional
+{'', :obj:`string <str>`}, optional
 
 {'C', 'F', 'A', or 'K'}, optional
 {'C', 'F', 'A', or 'K'}, optional
@@ -71,55 +71,55 @@
 {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
 
 {False, True, 'greedy', 'optimal'}
-{:xref_param_type:`False`, :xref_param_type:`True`, 'greedy', 'optimal'}
+{:obj:`False`, :obj:`True`, 'greedy', 'optimal'}
 
 {{'begin', 1}, {'end', 0}}, {string, int}
-{{'begin', 1}, {'end', 0}}, {:xref_param_type:`string <str>`, :xref_param_type:`int`}
+{{'begin', 1}, {'end', 0}}, {:obj:`string <str>`, :obj:`int`}
 
 callable f'(x,*args)
-:xref_param_type:`callable` f'(x,*args)
+:obj:`callable` f'(x,*args)
 
 callable ``fhess(x, *args)``, optional
-:xref_param_type:`callable` ``fhess(x, *args)``, optional
+:obj:`callable` ``fhess(x, *args)``, optional
 
 spmatrix (format: ``csr``, ``bsr``, ``dia`` or coo``)
-:xref_param_type:`spmatrix` (format: ``csr``, ``bsr``, ``dia`` or coo``)
+:obj:`spmatrix` (format: ``csr``, ``bsr``, ``dia`` or coo``)
 
 :ref:`strftime <strftime-strptime-behavior>`
 :ref:`strftime <strftime-strptime-behavior>`
 
 callable or :ref:`strftime <strftime-strptime-behavior>`
-:xref_param_type:`callable` or :ref:`strftime <strftime-strptime-behavior>`
+:obj:`callable` or :ref:`strftime <strftime-strptime-behavior>`
 
 callable or :ref:`strftime behavior <strftime-strptime-behavior>`
-:xref_param_type:`callable` or :ref:`strftime behavior <strftime-strptime-behavior>`
+:obj:`callable` or :ref:`strftime behavior <strftime-strptime-behavior>`
 
 list(int)
-:xref_param_type:`list`\(:xref_param_type:`int`)
+:obj:`list`\(:obj:`int`)
 
 list[int]
-:xref_param_type:`list`\[:xref_param_type:`int`]
+:obj:`list`\[:obj:`int`]
 
 dict(str, int)
-:xref_param_type:`dict`\(:xref_param_type:`str`, :xref_param_type:`int`)
+:obj:`dict`\(:obj:`str`, :obj:`int`)
 
 dict[str,  int]
-:xref_param_type:`dict`\[:xref_param_type:`str`,  :xref_param_type:`int`]
+:obj:`dict`\[:obj:`str`,  :obj:`int`]
 
 tuple(float, float)
-:xref_param_type:`tuple`\(:xref_param_type:`float`, :xref_param_type:`float`)
+:obj:`tuple`\(:obj:`float`, :obj:`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`]
+:obj:`dict`\[:obj:`tuple`\(:obj:`str`, :obj:`str`), :obj:`int`]
 """  # noqa: E501
 
 xref_ignore = {'or', 'in', 'of', 'default', 'optional'}
 
 
-def test_make_xref_param_type():
+def test_make_xref():
     for s in data.strip().split('\n\n'):
         param_type, expected_result = s.split('\n')
-        result = make_xref_param_type(
+        result = make_xref(
             param_type,
             xref_aliases,
             xref_ignore