ENH: merge duplicate sections (rather than raise)

This allows the docs for matplotlib 1.5.x to continue building.

numpydoc/docscrape.py

@@ -330,21 +330,27 @@ def _parse(self):
             if not section.startswith('..'):
                 section = (s.capitalize() for s in section.split(' '))
                 section = ' '.join(section)
-                if self.get(section):
-                    msg = ("The section %s appears twice in the docstring." %
-                           section)
-                    raise ValueError(msg)
 
             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 += ['']
+                else:
+                    existing_content = []
+                self[section] = existing_content + content
 
     # string conversion routines
 

numpydoc/tests/test_docscrape.py

@@ -220,10 +220,15 @@ def test_section_twice():
 
 Notes
 -----
-That should break...
+That should merge
 """
-    assert_raises(ValueError, NumpyDocString, doc_text)
 
+    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')