Improve error messages for see also parsing (#306)

* More informative error message for see also parse error.

* Improve _error_location method output.

* TST: Update test suite.

* CI: Update sphinx==1.6.5 job from Python 3.5 to 3.6

Author: rossbar

.travis.yml

@@ -22,7 +22,7 @@ jobs:
     - python: 3.7
     - python: 3.6
       env: SPHINX_SPEC="==2.1.0" SPHINXOPTS=""
-    - python: 3.5
+    - python: 3.6
       env: SPHINX_SPEC="==1.6.5" SPHINXOPTS=""
 
 before_install:

numpydoc/docscrape.py

@@ -294,7 +294,7 @@ def parse_item_name(text):
             """Match ':role:`name`' or 'name'."""
             m = self._func_rgx.match(text)
             if not m:
-                raise ParseError("%s is not a item name" % text)
+                self._error_location(f"Error parsing See Also entry {line!r}")
             role = m.group('role')
             name = m.group('name') if role else m.group('name2')
             return name, role, m.end()
@@ -329,7 +329,7 @@ def parse_item_name(text):
                 rest = list(filter(None, [description]))
                 items.append((funcs, rest))
             else:
-                raise ParseError("%s is not a item name" % line)
+                self._error_location(f"Error parsing See Also entry {line!r}")
         return items
 
     def _parse_index(self, section, content):
@@ -418,8 +418,8 @@ def _error_location(self, msg, error=True):
                 filename = inspect.getsourcefile(self._obj)
             except TypeError:
                 filename = None
-            msg = msg + (" in the docstring of %s in %s."
-                         % (self._obj, filename))
+            msg += f" in the docstring of {self._obj.__name__}"
+            msg += f" in {filename}." if filename else ""
         if error:
             raise ValueError(msg)
         else:

numpydoc/tests/test_docscrape.py

@@ -295,7 +295,8 @@ def test_section_twice():
 -----
 That should break...
 """
-    assert_raises(ValueError, NumpyDocString, doc_text)
+    with pytest.raises(ValueError, match="The section Notes appears twice"):
+        NumpyDocString(doc_text)
 
     # if we have a numpydoc object, we know where the error came from
     class Dummy:
@@ -332,19 +333,11 @@ def dummy_func(arg):
         Second note.
         """
 
-    try:
+    with pytest.raises(ValueError, match="Dummy class"):
         SphinxClassDoc(Dummy)
-    except ValueError as e:
-        # python 3 version or python 2 version
-        assert ("test_section_twice.<locals>.Dummy" in str(e)
-                or 'test_docscrape.Dummy' in str(e))
 
-    try:
+    with pytest.raises(ValueError, match="dummy_func"):
         SphinxFunctionDoc(dummy_func)
-    except ValueError as e:
-        # python 3 version or python 2 version
-        assert ("test_section_twice.<locals>.dummy_func" in str(e)
-                or 'function dummy_func' in str(e))
 
 
 def test_notes(doc):
@@ -842,13 +835,9 @@ def test_see_also_parse_error():
     --------
     :func:`~foo`
     """)
-    with assert_raises(ParseError) as err:
+    with pytest.raises(ValueError, match="See Also entry ':func:`~foo`'"):
         NumpyDocString(text)
 
-    s1 = str(r":func:`~foo` is not a item name in '\n    z(x,theta)\n\n    See Also\n    --------\n    :func:`~foo`\n    '")
-    s2 = str(err.value)
-    assert s1 == s2
-
 
 def test_see_also_print():
     class Dummy:
@@ -901,19 +890,16 @@ class BadSection:
         """
         pass
 
-    with warnings.catch_warnings(record=True) as w:
-        warnings.filterwarnings('always', '', UserWarning)
+    with pytest.warns(UserWarning, match="Unknown section Mope") as record:
         NumpyDocString(doc_text)
-        assert len(w) == 1
-        assert "Unknown section Mope" == str(w[0].message)
+    assert len(record) == 1
 
-    with warnings.catch_warnings(record=True) as w:
-        warnings.filterwarnings('always', '', UserWarning)
+    # SphinxClassDoc has _obj.__name__ == "BadSection". Test that this is
+    # included in the message
+    msg_match = "Unknown section Nope in the docstring of BadSection"
+    with pytest.warns(UserWarning, match=msg_match) as record:
         SphinxClassDoc(BadSection)
-        assert len(w) == 1
-        assert('test_docscrape.test_unknown_section.<locals>.BadSection'
-               in str(w[0].message)
-               or 'test_docscrape.BadSection' in str(w[0].message))
+    assert len(record) == 1
 
 
 doc7 = NumpyDocString("""

numpydoc/tests/test_main.py

@@ -87,7 +87,7 @@ def test_render_object_returns_correct_exit_status():
         'numpydoc.tests.test_main._capture_stdout')
     assert exit_status == 0
 
-    with pytest.raises(numpydoc.docscrape.ParseError):
+    with pytest.raises(ValueError):
         numpydoc.__main__.render_object(
             'numpydoc.tests.test_main._invalid_docstring')