Correctly validate parameters under the "Other Parameters" section (#337)

* Fix invalid "PR01" error when parameter is specified in "Other Parameters" section.

* Fix 'foo' docstring in doc/example.py

* Change "PR03" (wrong parameters order) validation test

* Revert "PR03" changes.

Author: dcbr

doc/example.py

@@ -35,7 +35,7 @@
 # numpy module itself, unabbreviated.
 
 
-def foo(var1, var2, *args, long_var_name='hi', **kwargs):
+def foo(var1, var2, *args, long_var_name='hi', only_seldom_used_keyword=0, **kwargs):
     r"""Summarize the function in one line.
 
     Several sentences providing an extended description. Refer to
@@ -55,8 +55,6 @@ def foo(var1, var2, *args, long_var_name='hi', **kwargs):
         Other arguments.
     long_var_name : {'hi', 'ho'}, optional
         Choices in brackets, default first when optional.
-    **kwargs : dict
-        Keyword arguments.
 
     Returns
     -------
@@ -70,10 +68,14 @@ def foo(var1, var2, *args, long_var_name='hi', **kwargs):
 
     Other Parameters
     ----------------
-    only_seldom_used_keywords : type
-        Explanation.
-    common_parameters_listed_above : type
-        Explanation.
+    only_seldom_used_keyword : int, optional
+        Infrequently used parameters can be described under this optional
+        section to prevent cluttering the Parameters section.
+    **kwargs : dict
+        Other infrequently used keyword arguments. Note that all keyword
+        arguments appearing after the first parameter specified under the
+        Other Parameters section, should also be described under this
+        section.
 
     Raises
     ------

numpydoc/tests/test_validate.py

@@ -431,6 +431,33 @@ def multiple_variables_on_one_line(self, matrix, a, b, i, j):
         """
         pass
 
+    def other_parameters(self, param1, param2):
+        """
+        Ensure "Other Parameters" are recognized.
+
+        The second parameter is used infrequently, so it is put in the
+        "Other Parameters" section.
+
+        Parameters
+        ----------
+        param1 : bool
+            Description of commonly used parameter.
+
+        Other Parameters
+        ----------------
+        param2 : str
+            Description of infrequently used parameter.
+
+        See Also
+        --------
+        related : Something related.
+
+        Examples
+        --------
+        >>> result = 1 + 1
+        """
+        pass
+
 
 class BadGenericDocStrings:
     """Everything here has a bad docstring
@@ -1060,6 +1087,7 @@ def test_good_class(self, capsys):
             "no_returns",
             "empty_returns",
             "multiple_variables_on_one_line",
+            "other_parameters",
             "warnings",
         ],
     )

numpydoc/validate.py

@@ -261,14 +261,26 @@ def extended_summary(self):
             return " ".join(self.doc["Summary"])
         return " ".join(self.doc["Extended Summary"])
 
-    @property
-    def doc_parameters(self):
+    def _doc_parameters(self, sections):
         parameters = collections.OrderedDict()
-        for names, type_, desc in self.doc["Parameters"]:
-            for name in names.split(", "):
-                parameters[name] = (type_, desc)
+        for section in sections:
+            for names, type_, desc in self.doc[section]:
+                for name in names.split(", "):
+                    parameters[name] = (type_, desc)
         return parameters
 
+    @property
+    def doc_parameters(self):
+        return self._doc_parameters(["Parameters"])
+
+    @property
+    def doc_other_parameters(self):
+        return self._doc_parameters(["Other Parameters"])
+
+    @property
+    def doc_all_parameters(self):
+        return self._doc_parameters(["Parameters", "Other Parameters"])
+
     @property
     def signature_parameters(self):
         def add_stars(param_name, info):
@@ -307,22 +319,22 @@ def add_stars(param_name, info):
     def parameter_mismatches(self):
         errs = []
         signature_params = self.signature_parameters
-        doc_params = tuple(self.doc_parameters)
-        missing = set(signature_params) - set(doc_params)
+        all_params = tuple(self.doc_all_parameters)
+        missing = set(signature_params) - set(all_params)
         if missing:
             errs.append(error("PR01", missing_params=str(missing)))
-        extra = set(doc_params) - set(signature_params)
+        extra = set(all_params) - set(signature_params)
         if extra:
             errs.append(error("PR02", unknown_params=str(extra)))
         if (
             not missing
             and not extra
-            and signature_params != doc_params
-            and not (not signature_params and not doc_params)
+            and signature_params != all_params
+            and not (not signature_params and not all_params)
         ):
             errs.append(
                 error(
-                    "PR03", actual_params=signature_params, documented_params=doc_params
+                    "PR03", actual_params=signature_params, documented_params=all_params
                 )
             )
 
@@ -333,7 +345,7 @@ def directives_without_two_colons(self):
         return DIRECTIVE_PATTERN.findall(self.raw_doc)
 
     def parameter_type(self, param):
-        return self.doc_parameters[param][0]
+        return self.doc_all_parameters[param][0]
 
     @property
     def see_also(self):
@@ -542,7 +554,7 @@ def validate(obj_name):
     # PR03: Wrong parameters order
     errs += doc.parameter_mismatches
 
-    for param, kind_desc in doc.doc_parameters.items():
+    for param, kind_desc in doc.doc_all_parameters.items():
         if not param.startswith("*"):  # Check can ignore var / kwargs
             if not doc.parameter_type(param):
                 if ":" in param: