BUG: Fix returns parsing no name (#429)

* TST: Add test case.

* MAINT: Adjust logic for parameter lines with : char.

Adjust logic in parameter line splitting to avoid bug
where Returns objects containing sphinx roles are improperly
parsed.

Author: rossbar

numpydoc/docscrape.py

@@ -226,10 +226,14 @@ def _parse_param_list(self, content, single_element_is_type=False):
         params = []
         while not r.eof():
             header = r.read().strip()
-            if " :" in header:
-                arg_name, arg_type = header.split(" :", maxsplit=1)
-                arg_name, arg_type = arg_name.strip(), arg_type.strip()
+            if " : " in header:
+                arg_name, arg_type = header.split(" : ", maxsplit=1)
             else:
+                # NOTE: param line with single element should never have a
+                # a " :" before the description line, so this should probably
+                # warn.
+                if header.endswith(" :"):
+                    header = header[:-2]
                 if single_element_is_type:
                     arg_name, arg_type = "", header
                 else:

numpydoc/tests/test_docscrape.py

@@ -980,6 +980,21 @@ def test_empty_first_line():
 )
 
 
+def test_returns_with_roles_no_names():
+    """Make sure colons that are part of sphinx roles are not misinterpreted
+    as type separator in returns section. See gh-428."""
+    docstring = NumpyDocString(
+        """
+        Returns
+        -------
+        str or :class:`NumpyDocString`
+        """
+    )
+    expected = "str or :class:`NumpyDocString`"  # not "str or : class:...
+    assert docstring["Returns"][0].type == expected
+    assert expected in str(docstring)
+
+
 def test_trailing_colon():
     assert doc8["Parameters"][0].name == "data"