Fix section mix bug (#424)

* fix the bug and add docs

* update docs

Author: shacharoo

docs/error_codes.rst

@@ -10,7 +10,7 @@ Default conventions
 -------------------
 
 Not all error codes are checked for by default.  There are three
-conventions that may be used by pydocstyle: pep257, numpy and google.
+conventions that may be used by pydocstyle: ``pep257``, ``numpy`` and ``google``.
 
 The pep257 convention, which is enabled by default in pydocstyle,
 checks for all of the above errors except for D203, D212, D213, D214,
@@ -28,6 +28,17 @@ running pydocstyle from the command line or by specifying the
 convention in a configuration file.  See the :ref:`cli_usage` section
 for more details.
 
+.. note::
+
+  It makes no sense to check the same docstring for both ``numpy`` and ``google``
+  conventions. Therefore, if we successfully detect that a docstring is in the
+  ``numpy`` style, we don't check it for ``google``.
+
+  The reason ``numpy`` style takes precedence over ``google`` is that the
+  heuristics of detecting it are better, and we don't want to enforce users to
+  provide external hints to `pydocstyle` in order to let it know which style
+  docstrings are written in.
+
 Publicity
 ---------
 

docs/release_notes.rst

@@ -28,6 +28,8 @@ Bug Fixes
   ``\N...`` anymore. These are considered intended elements of the docstring
   and thus should not be escaped by using a raw docstring (#365).
 * Fix decorator parsing (#411).
+* Google-style sections no longer cause false errors when used with
+  Numpy-style sections (#388, #424).
 
 4.0.1 - August 14th, 2019
 -------------------------

src/pydocstyle/checker.py

@@ -824,7 +824,6 @@ def _suspected_as_section(_line):
                                    False)
                     for i in suspected_section_indices)
 
-
         # Now that we have manageable objects - rule out false positives.
         contexts = (c for c in contexts if ConventionChecker._is_docstring_section(c))
 
@@ -833,12 +832,11 @@ def _suspected_as_section(_line):
         for a, b in pairwise(contexts, None):
             end = -1 if b is None else b.original_index
             yield SectionContext(a.section_name,
-                                     a.previous_line,
-                                     a.line,
-                                     lines[a.original_index + 1:end],
-                                     a.original_index,
-                                     b is None)
-
+                                 a.previous_line,
+                                 a.line,
+                                 lines[a.original_index + 1:end],
+                                 a.original_index,
+                                 b is None)
 
     def _check_numpy_sections(self, lines, definition, docstring):
         """NumPy-style docstring sections checks.
@@ -860,10 +858,14 @@ def _check_numpy_sections(self, lines, definition, docstring):
         Yields all violation from `_check_numpy_section` for each valid
         Numpy-style section.
         """
+        found_any_numpy_section = False
         for ctx in self._get_section_contexts(lines,
                                               self.NUMPY_SECTION_NAMES):
+            found_any_numpy_section = True
             yield from self._check_numpy_section(docstring, definition, ctx)
 
+        return found_any_numpy_section
+
     def _check_google_sections(self, lines, definition, docstring):
         """Google-style docstring section checks.
 
@@ -895,8 +897,10 @@ def check_docstring_sections(self, definition, docstring):
         lines = docstring.split("\n")
         if len(lines) < 2:
             return
-        yield from self._check_numpy_sections(lines, definition, docstring)
-        yield from self._check_google_sections(lines, definition, docstring)
+
+        found_numpy = yield from self._check_numpy_sections(lines, definition, docstring)
+        if not found_numpy:
+            yield from self._check_google_sections(lines, definition, docstring)
 
 
 parse = Parser()

src/tests/test_cases/sections.py

@@ -414,3 +414,14 @@ def test_missing_args_static_method(a, x, y, z=3, t=1):  # noqa: D213, D407
             Yet another parameter.
 
         """
+
+    @staticmethod
+    def test_mixing_numpy_and_google(danger):  # noqa: D213
+        """Repro for #388.
+
+        Parameters
+        ----------
+        danger
+            Zoneeeeee!
+
+        """