ENH: Just use obj

Author: larsoner

.gitignore

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

.travis.yml

@@ -1,23 +1,21 @@
 # After changing this file, check it on:
 #   http://lint.travis-ci.org/
 language: python
+dist: xenial
 sudo: false
-env:
-  - SPHINX_SPEC="Sphinx==1.2.3"
-  - SPHINX_SPEC="Sphinx"
 matrix:
   include:
-    - python: 3.6
+    - python: 3.7
+      env: SPHINX_SPEC="==1.2.3" SPHINXOPTS=""
+    - python: 3.7
     - python: 2.7
-      env:
-        - SPHINXOPTS='-W'
 cache:
   directories:
     - $HOME/.cache/pip
 before_install:
   - sudo apt-get install texlive texlive-latex-extra latexmk
   - pip install --upgrade pip setuptools  # Upgrade pip and setuptools to get ones with `wheel` support
-  - pip install pytest numpy matplotlib ${SPHINX_SPEC}
+  - pip install pytest numpy matplotlib sphinx${SPHINX_SPEC}
 script:
   - |
     python setup.py sdist

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -nWT --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build

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', 'type_without_description', 'BadException'}
 
 # 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

@@ -70,26 +70,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
@@ -85,15 +85,15 @@ 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)
                 if param.name:
                     out += self._str_indent([named_fmt % (param.name.strip(),
                                                           param_type)])
                 else:
-                   out += self._str_indent([unnamed_fmt % param_type.strip()])
+                    out += self._str_indent([unnamed_fmt % param_type.strip()])
                 if not param.desc:
                     out += self._str_indent(['..'], 8)
                 else:
@@ -168,10 +168,8 @@ def _process_param(self, param, desc, fake_autosummary):
 
         prefix = getattr(self, '_name', '')
         if prefix:
-            autosum_prefix = '~%s.' % prefix
             link_prefix = '%s.' % prefix
         else:
-            autosum_prefix = ''
             link_prefix = ''
 
         # Referenced object has a docstring
@@ -227,14 +225,13 @@ 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)
-(??)                    out += self._str_indent(['%s : %s' % (display_param,
-(??)                                                          param.type)])
-(??)                else:
-(??)                    out += self._str_indent([display_param])
+                    parts.append(param_type)
+                out += self._str_indent([' : '.join(parts)])
+
                 if desc and self.use_blockquotes:
                     out += ['']
                 elif not desc:

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:
@@ -223,7 +223,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)
@@ -248,6 +248,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,
@@ -382,11 +384,11 @@ def _strip_blank_lines(s):
     return s
 
 
-def line_by_line_compare(a, b):
+def line_by_line_compare(a, b, n_lines=None):
     a = textwrap.dedent(a)
     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')]
+    a = [l.rstrip() for l in _strip_blank_lines(a).split('\n')][:n_lines]
+    b = [l.rstrip() for l in _strip_blank_lines(b).split('\n')][:n_lines]
     assert len(a) == len(b)
     for ii, (aa, bb) in enumerate(zip(a, b)):
         assert aa == bb
@@ -518,8 +520,7 @@ def test_yield_str():
     The number of bananas.
 int
     The number of unknowns.
-
-.. index:: """)
+""")
 
 
 def test_receives_str():
@@ -537,8 +538,7 @@ def test_receives_str():
     The number of bananas.
 c : int
     The number of oranges.
-
-.. index:: """)
+""")
 
 
 def test_no_index_in_str():
@@ -1200,8 +1200,6 @@ def test_class_members_doc():
     b
     c
 
-    .. index::
-
     """)
 
 
@@ -1422,7 +1420,7 @@ def test_autoclass():
 .. rubric:: Methods
 
 
-    ''')
+    ''', 5)
 
 
 xref_doc_txt = """
@@ -1442,7 +1440,7 @@ def test_autoclass():
     List of integers
 p4 : :class:`pandas.DataFrame`
     A dataframe
-p5 : sequence of int
+p5 : sequence of `int`
     A sequence
 
 Returns
@@ -1458,37 +1456,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_numpydoc.py

@@ -10,6 +10,9 @@ class MockConfig():
     numpydoc_show_class_members = True
     numpydoc_show_inherited_class_members = True
     numpydoc_class_members_toctree = True
+    numpydoc_xref_param_type = False
+    numpydoc_xref_aliases = {}
+    numpydoc_xref_ignore = set()
     templates_path = []
     numpydoc_edit_link = False
     numpydoc_citation_re = '[a-z0-9_.-]+'
@@ -41,7 +44,7 @@ def test_mangle_docstrings():
     doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'members': ['upper']}, lines)
     assert 'rpartition' not in [x.strip() for x in lines]
     assert 'upper' in [x.strip() for x in lines]
-    
+
     lines = s.split('\n')
     doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'exclude-members': ALL}, lines)
     assert 'rpartition' not in [x.strip() for x in lines]