ENH: merge duplicate sections (rather than raise)

numpydoc/docscrape.py

@@ -128,8 +128,8 @@ class NumpyDocString(collections.Mapping):
         'See Also': [],
         'Notes': [],
         'Warnings': [],
-        'References': '',
-        'Examples': '',
+        'References': [],
+        'Examples': [],
         'index': {}
     }
 
@@ -347,20 +347,25 @@ def _parse(self):
             if not section.startswith('..'):
                 section = (s.capitalize() for s in section.split(' '))
                 section = ' '.join(section)
-                if self.get(section):
-                    self._error_location("The section %s appears twice"
-                                         % section)
 
             if section in ('Parameters', 'Returns', 'Yields', 'Raises',
                            'Warns', 'Other Parameters', 'Attributes',
                            'Methods'):
-                self[section] = self._parse_param_list(content)
+                existing_content = self.get(section, [])
+                self[section] = (existing_content +
+                                 self._parse_param_list(content))
+
             elif section.startswith('.. index::'):
                 self['index'] = self._parse_index(section, content)
             elif section == 'See Also':
-                self['See Also'] = self._parse_see_also(content)
+                existing_content = self.get('See Also', [])
+                self['See Also'] = (existing_content +
+                                    self._parse_see_also(content))
             else:
-                self[section] = content
+                existing_content = self.get(section, [])
+                if existing_content:
+                    existing_content += ['']
+                self[section] = existing_content + content
 
     def _error_location(self, msg, error=True):
         if hasattr(self, '_obj'):

numpydoc/tests/test_docscrape.py

@@ -241,59 +241,15 @@ def test_section_twice():
 
 Notes
 -----
-That should break...
+That should merge
 """
-    assert_raises(ValueError, NumpyDocString, doc_text)
-
-    # if we have a numpydoc object, we know where the error came from
-    class Dummy(object):
-        """
-        Dummy class.
-
-        Notes
-        -----
-        First note.
-
-        Notes
-        -----
-        Second note.
-
-        """
-        def spam(self, a, b):
-            """Spam\n\nSpam spam."""
-            pass
-
-        def ham(self, c, d):
-            """Cheese\n\nNo cheese."""
-            pass
-
-    def dummy_func(arg):
-        """
-        Dummy function.
-
-        Notes
-        -----
-        First note.
-
-        Notes
-        -----
-        Second note.
-        """
-
-    try:
-        SphinxClassDoc(Dummy)
-    except ValueError as e:
-        # python 3 version or python 2 version
-        assert_true("test_section_twice.<locals>.Dummy" in str(e)
-                    or 'test_docscrape.Dummy' in str(e))
 
-    try:
-        SphinxFunctionDoc(dummy_func)
-    except ValueError as e:
-        # python 3 version or python 2 version
-        assert_true("test_section_twice.<locals>.dummy_func" in str(e)
-                    or 'function dummy_func' in str(e))
+    target = ['See the next note for more information',
+              '',
+              'That should merge']
 
+    doc = NumpyDocString(doc_text)
+    assert doc['Notes'] == target
 
 def test_notes():
     assert doc['Notes'][0].startswith('Instead')