ALTERNATIVE: overload xref_ignore config value

Author: rossbar

doc/install.rst

@@ -76,30 +76,26 @@ 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
+numpydoc_xref_ignore : set or ``"all"``
+    How to handle terms not in ``numpydoc_xref_aliases`` when
+    ``numpydoc_xref_aliases=True``. The value can either be a ``set`` 
+    containing terms to ignore, or ``"all"``. In the former case, the set
+    contains words not to cross-reference. Most likely, these are common words
     used in parameter type descriptions that may be confused for
     classes of the same name. For example::
 
         numpydoc_xref_ignore = {'type', 'optional', 'default'}
 
     The default is an empty set.
-numpydoc_xref_wrap_all : bool
-    Whether to wrap unrecognized terms in ``param_type`` in the default
-    ``:obj:`` role. The default is ``True``.
-    An unrecognized term is one that:
-
-    1. Is in neither ``numpydoc_xref_aliases`` nor ``numpydoc_xref_ignore``.
-    2. Is not already wrapped in a ReST role.
 
+    If the ``numpydoc_xref_ignore="all"``, then all unrecognized terms are
+    ignored, i.e. terms not in ``numpydoc_xref_aliases`` are *not* wrapped in
+    ``:obj:`` roles.
     This configuration parameter may be useful if you only want create
-    cross references for a small set of terms. In this case, including the
+    cross references for a small number of terms. In this case, including the
     desired cross reference mappings in ``numpydoc_xref_aliases`` and setting
-    ``numpydoc_xref_wrap_all = False`` is more convenient than adding all of
-    the non-linked terms to the ``numpydoc_xref_ignore`` set.
-
-    If ``numpydoc_xref_param_type`` is set to ``False``, this config parameter
-    has no effect.
+    ``numpydoc_xref_ignore="all"`` is more convenient than explicitly listing
+    terms to ignore in a set.
 numpydoc_edit_link : bool
   .. deprecated:: edit your HTML template instead
 

numpydoc/docscrape_sphinx.py

@@ -30,7 +30,6 @@ def load_config(self, config):
         self.xref_param_type = config.get('xref_param_type', False)
         self.xref_aliases = config.get('xref_aliases', dict())
         self.xref_ignore = config.get('xref_ignore', set())
-        self.xref_wrap_all = config.get('xref_wrap_all', True)
         self.template = config.get('template', None)
         if self.template is None:
             template_dirs = [os.path.join(os.path.dirname(__file__), 'templates')]
@@ -78,8 +77,7 @@ def _str_returns(self, name='Returns'):
                     param_type = make_xref(
                         param_type,
                         self.xref_aliases,
-                        self.xref_ignore,
-                        self.xref_wrap_all
+                        self.xref_ignore
                     )
                 if param.name:
                     out += self._str_indent([named_fmt % (param.name.strip(),
@@ -220,8 +218,7 @@ def _str_param_list(self, name, fake_autosummary=False):
                         param_type = make_xref(
                             param_type,
                             self.xref_aliases,
-                            self.xref_ignore,
-                            self.xref_wrap_all
+                            self.xref_ignore
                         )
                     parts.append(param_type)
                 out += self._str_indent([' : '.join(parts)])

numpydoc/numpydoc.py

@@ -155,7 +155,6 @@ def mangle_docstrings(app, what, name, obj, options, lines):
            'xref_param_type': app.config.numpydoc_xref_param_type,
            'xref_aliases': app.config.numpydoc_xref_aliases_complete,
            'xref_ignore': app.config.numpydoc_xref_ignore,
-           'xref_wrap_all': app.config.numpydoc_xref_wrap_all,
            }
 
     cfg.update(options or {})
@@ -255,7 +254,6 @@ def setup(app, get_doc_object_=get_doc_object):
     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)
-    app.add_config_value('numpydoc_xref_wrap_all', True, True)
 
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)

numpydoc/tests/test_numpydoc.py

@@ -15,7 +15,6 @@ class MockConfig():
     numpydoc_xref_aliases = {}
     numpydoc_xref_aliases_complete = deepcopy(DEFAULT_LINKS)
     numpydoc_xref_ignore = set()
-    numpydoc_xref_wrap_all = True
     templates_path = []
     numpydoc_edit_link = False
     numpydoc_citation_re = '[a-z0-9_.-]+'

numpydoc/tests/test_xref.py

@@ -212,4 +212,8 @@ def test_make_xref(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
+    assert make_xref(param_type, xref_aliases, xref_ignore="all") == expected_result
+
+def test_xref_ignore_is_all():
+    with pytest.raises(TypeError, match="must be a set or 'all'"):
+        make_xref("array_like", xref_aliases, xref_ignore="foo")

numpydoc/xref.py

@@ -94,7 +94,7 @@
 }
 
 
-def make_xref(param_type, xref_aliases, xref_ignore, wrap_unknown=True):
+def make_xref(param_type, xref_aliases, xref_ignore):
     """Parse and apply appropriate sphinx role(s) to `param_type`.
 
     The :obj: role is the default.
@@ -106,27 +106,36 @@ def make_xref(param_type, xref_aliases, xref_ignore, wrap_unknown=True):
     xref_aliases : dict
         Mapping used to resolve common abbreviations and aliases
         to fully qualified names that can be cross-referenced.
-    xref_ignore : set
-        Words not to cross-reference.
-    wrap_unknown : bool, default=True
-        Toggle whether to wrap unrecognized terms in the default :obj: role,
-        default is `True`. Unrecognized terms include those that are in
-        neither `xref_aliases` nor `xref_ignore` and are not already wrapped
-        in an rST role.
+    xref_ignore : set or "all"
+        A set containing words not to cross-reference. Instead of a set, the
+        string 'all' can be given to ignore all unrecognized terms. 
+        Unrecognized terms include those that are not in `xref_aliases` and
+        are not already wrapped in a reST role.
 
     Returns
     -------
     out : str
         Text with fully-qualified names and terms that may be wrapped in a
         ``:obj:`` role.
     """
+    ignore_set = xref_ignore
+    wrap_unknown = True
+    if isinstance(xref_ignore, str):
+        if xref_ignore.lower() == "all":
+            wrap_unknown = False
+            ignore_set = set()
+        else:
+            raise TypeError(
+                "xref_ignore must be a set or 'all', got {}".format(xref_ignore)
+            )
+
     if param_type in xref_aliases:
         link, title = xref_aliases[param_type], param_type
         param_type = link
     else:
         link = title = param_type
 
-    if QUALIFIED_NAME_RE.match(link) and link not in xref_ignore:
+    if QUALIFIED_NAME_RE.match(link) and link not in ignore_set:
         if link != title:
             return ':obj:`%s <%s>`' % (title, link)
         if wrap_unknown:
@@ -147,9 +156,7 @@ def _split_and_apply_re(s, pattern):
                 if pattern.match(tok):
                     results.append(tok)
                 else:
-                    res = make_xref(
-                        tok, xref_aliases, xref_ignore, wrap_unknown
-                    )
+                    res = make_xref(tok, xref_aliases, xref_ignore)
                     # Opening brackets immediately after a role is
                     # bad markup. Detect that and add backslash.
                     # :role:`type`( to :role:`type`\(