diff --git a/doc/example.py b/doc/example.py index b3ba6869..43defc5b 100644 --- a/doc/example.py +++ b/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 ------ diff --git a/numpydoc/tests/test_validate.py b/numpydoc/tests/test_validate.py index 10f95e4f..ecbe7031 100644 --- a/numpydoc/tests/test_validate.py +++ b/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", ], ) diff --git a/numpydoc/validate.py b/numpydoc/validate.py index 3c8d60ec..91aca6b1 100644 --- a/numpydoc/validate.py +++ b/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: