From aaf486d37ccedc341ed4780372ac118a8e561a0d Mon Sep 17 00:00:00 2001 From: Nathan Abel Date: Sun, 6 Oct 2019 23:24:17 -0400 Subject: [PATCH 1/5] TST: Allow for multiple variables on the same line in doctests Allow for multiple variables to share the same type and description in documentation. For example, `i, j, k : int` Would be three variables, i, j, and k, which are all ints. --- scripts/validate_docstrings.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 401eaf8ff5ed5..4d1ccc80d1cfb 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -422,10 +422,11 @@ def needs_summary(self): @property def doc_parameters(self): - return collections.OrderedDict( - (name, (type_, "".join(desc))) - for name, type_, desc in self.doc["Parameters"] - ) + parameters = collections.OrderedDict() + for names, type_, desc in self.doc["Parameters"]: + for name in names.split(", "): + parameters[name] = (type_, "".join(desc)) + return parameters @property def signature_parameters(self): From 6dcb021d4150cf739a761832eab203d7dababe6e Mon Sep 17 00:00:00 2001 From: Nathan Abel Date: Mon, 7 Oct 2019 08:38:25 -0400 Subject: [PATCH 2/5] DOC: Fix order in series.py This was generating errors because it got fixed in master after I made the branch. I'm sure this will be a merge conflict, and I can work it out there first. --- pandas/core/series.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 97e8a2dbac7f5..19d201917f3c8 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2076,12 +2076,12 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs): Parameters ---------- - skipna : bool, default True - Exclude NA/null values. If the entire Series is NA, the result - will be NA. axis : int, default 0 For compatibility with DataFrame.idxmin. Redundant for application on Series. + skipna : bool, default True + Exclude NA/null values. If the entire Series is NA, the result + will be NA. *args, **kwargs Additional keywords have no effect but might be accepted for compatibility with NumPy. @@ -2146,12 +2146,12 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): Parameters ---------- - skipna : bool, default True - Exclude NA/null values. If the entire Series is NA, the result - will be NA. axis : int, default 0 For compatibility with DataFrame.idxmax. Redundant for application on Series. + skipna : bool, default True + Exclude NA/null values. If the entire Series is NA, the result + will be NA. *args, **kwargs Additional keywords have no effect but might be accepted for compatibility with NumPy. From fea628fc20e6ff6687b3481aa49f3651e0cf91d7 Mon Sep 17 00:00:00 2001 From: Nathan Abel Date: Mon, 7 Oct 2019 20:16:36 -0400 Subject: [PATCH 3/5] Added test Added a test for if the spacing is off on a multivariable oneline parameter descriptoin --- scripts/tests/test_validate_docstrings.py | 34 +++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 85e5bf239cbfa..9613c3fbc03d8 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -39,6 +39,23 @@ def plot(self, kind, color="blue", **kwargs): """ pass + def swap(self, arr, i, j, *args, **kwargs): + """ + Swap two indecies on an array. + + Parameters + ---------- + arr : List + The list having indexes swapped. + i, j : int + The indexes being swapped. + *args, **kwargs + Extraneous parameters are being permitted. + """ + temp = arr[i] + arr[i] = arr[j] + arr[j] = temp + def sample(self): """ Generate and return a random number. @@ -634,6 +651,17 @@ def list_incorrect_parameter_type(self, kind): """ pass + def bad_parameter_spacing(self, a, b): + """ + The parameters on the same line have an extra space between them. + + Parameters + ---------- + a, b : int + Foo bar baz. + """ + pass + class BadReturns: def return_not_documented(self): @@ -827,6 +855,7 @@ def test_good_class(self, capsys): "func", [ "plot", + "swap", "sample", "random_letters", "sample_values", @@ -1002,6 +1031,11 @@ def test_bad_generic_functions(self, capsys, func): "list_incorrect_parameter_type", ('Parameter "kind" type should use "str" instead of "string"',), ), + ( + "BadParameters", + "bad_parameter_spacing", + ("Parameters {b} not documented", "Unknown parameters { b}"), + ), pytest.param( "BadParameters", "blank_lines", From a98fabdb0e3ea1ae57fc703cd2ba417c29012bbb Mon Sep 17 00:00:00 2001 From: Nathan Abel Date: Mon, 7 Oct 2019 20:36:26 -0400 Subject: [PATCH 4/5] TST: Correct test for multiple variables on one line Adds a test for if multiple variables are typed and described on the same line in a docstring. --- scripts/tests/test_validate_docstrings.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 9613c3fbc03d8..4bc9c33d3755b 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -273,6 +273,23 @@ def say_hello(): else: return None + def multiple_variables_on_one_line(self, matrix, a, b, i, j): + """ + Swap two values in a matrix. + + Parameters + ---------- + matrix : list of list + A double list that represents a matrix. + a, b : int + The indicies of the first value. + i, j : int + The indicies of the second value. + """ + temp = matrix[a][b] + matrix[a][b] = matrix[i][j] + matrix[i][j] = temp + class BadGenericDocStrings: """Everything here has a bad docstring @@ -866,6 +883,7 @@ def test_good_class(self, capsys): "good_imports", "no_returns", "empty_returns", + "multiple_variables_on_one_line", ], ) def test_good_functions(self, capsys, func): From c8931a2d130a1392c5b4635c02fd7b365d66a0a6 Mon Sep 17 00:00:00 2001 From: Nathan Abel Date: Thu, 10 Oct 2019 14:20:44 -0400 Subject: [PATCH 5/5] TST: Change tests to just pass, fix typos Removed the functionality of tests, since it isn't important for documentation. Fixed a couple of small typos. --- scripts/tests/test_validate_docstrings.py | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 4bc9c33d3755b..c8b5b6d5d7097 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -41,20 +41,18 @@ def plot(self, kind, color="blue", **kwargs): def swap(self, arr, i, j, *args, **kwargs): """ - Swap two indecies on an array. + Swap two indicies on an array. Parameters ---------- - arr : List + arr : list The list having indexes swapped. i, j : int The indexes being swapped. *args, **kwargs Extraneous parameters are being permitted. """ - temp = arr[i] - arr[i] = arr[j] - arr[j] = temp + pass def sample(self): """ @@ -286,9 +284,7 @@ def multiple_variables_on_one_line(self, matrix, a, b, i, j): i, j : int The indicies of the second value. """ - temp = matrix[a][b] - matrix[a][b] = matrix[i][j] - matrix[i][j] = temp + pass class BadGenericDocStrings: