DOC/CLN: Fix errors in Series docstrings

[dsaxton]

Fixes (or starts to fix) a few errors in Series docstrings. On a related note, it seems validate_docstrings.py yields this error for a large number of docstrings:

The first line of the Returns section should contain only the type, unless multiple values are being returned

which seems to happen whenever the return value is named. Should these be errors?

[codecov]

Codecov Report

Merging #24945 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #24945   +/-   ##
=======================================
  Coverage   92.37%   92.37%           
=======================================
  Files         166      166           
  Lines       52388    52388           
=======================================
  Hits        48396    48396           
  Misses       3992     3992

Flag	Coverage Δ
#multiple	90.8% <ø> (ø)	⬆️
#single	42.9% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/core/series.py	93.68% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0c4113f...6791923. Read the comment docs.

[codecov]

Codecov Report

Merging #24945 into master will decrease coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #24945      +/-   ##
==========================================
- Coverage   92.37%   92.35%   -0.03%     
==========================================
  Files         166      166              
  Lines       52408    52314      -94     
==========================================
- Hits        48412    48312     -100     
- Misses       3996     4002       +6

Flag	Coverage Δ
#multiple	90.78% <ø> (-0.01%)	⬇️
#single	42.84% <ø> (-0.03%)	⬇️

Impacted Files	Coverage Δ
pandas/core/series.py	93.69% <ø> (ø)	⬆️
pandas/core/groupby/ops.py	94.15% <0%> (-2.58%)	⬇️
pandas/core/generic.py	96.39% <0%> (-0.24%)	⬇️
pandas/core/groupby/generic.py	86.98% <0%> (-0.18%)	⬇️
pandas/core/frame.py	96.65% <0%> (-0.16%)	⬇️
pandas/core/internals/managers.py	95.95% <0%> (-0.11%)	⬇️
pandas/util/testing.py	88.05% <0%> (-0.09%)	⬇️
pandas/core/internals/blocks.py	94.1% <0%> (-0.07%)	⬇️
pandas/core/resample.py	97.22% <0%> (-0.02%)	⬇️
pandas/core/panel.py	97.9% <0%> (-0.01%)	⬇️
... and 16 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2e38d55...1205404. Read the comment docs.

[pep8speaks]

Hello @dsaxton! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on February 07, 2019 at 01:56 Hours UTC

[WillAyd]

which seems to happen whenever the return value is named. Should these be errors?

Yea this is intentional. Unless multiple values are being returned should just have a type in the Returns section

[WillAyd]

Minor comments but generally look good. How do the validation scripts look against these?

[WillAyd]

Split this into a type and description

[WillAyd]

You can put code blocks in double backticks for better rendering, so ``buf=None``

[dsaxton]

This should be the output for the docstrings edited so far in this PR.

to_string

3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.to_string" correct. :)

to_dict

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.to_dict" correct. :)

to_frame

3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.to_frame" correct. :)

to_sparse

(I think the first error is wrong here because "integer" is actually a string in the docstring. For this one I'm not familiar enough with the method to add a good description. Also, I think this will be deprecated soon anyways?)

2 Errors found:
	Parameter "kind" type should use "int" instead of "integer"
	Parameter "kind" has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

count

3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.count" correct. :)

mode

2 Warnings found:
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.mode" correct. :)

drop_duplicates

(This is another one where the lowercase letter is an argument option.)

1 Errors found:
	Parameter "keep" description should start with a capital letter
1 Warnings found:
	No extended summary found

duplicated

(Same here.)

1 Errors found:
	Parameter "keep" description should start with a capital letter

idxmin

2 Errors found:
	Parameters {*args, **kwargs} not documented
	Unknown parameters {*args, **kwargs}

idxmax

2 Errors found:
	Parameters {*args, **kwargs} not documented
	Unknown parameters {*args, **kwargs}

round

1 Errors found:
	Parameters {**kwargs, *args} not documented
2 Warnings found:
	No extended summary found
	No examples section found

quantile

6 Errors found:
	Parameter "q" description should start with a capital letter
	Parameter "q" description should finish with "."
	Parameter "interpolation" has no description
	Return value description should start with a capital letter
	Missing description for See Also "core.window.Rolling.quantile" reference
	Missing description for See Also "numpy.percentile" reference

corr

6 Errors found:
	Parameter "other" has no description
	Parameter "method" description should start with a capital letter
	Parameter "method" description should finish with "."
	Parameter "min_periods" description should finish with "."
	Return value has no description
	flake8 error: E124 closing bracket does not match visual indentation
2 Warnings found:
	No extended summary found
	See Also section not found

cov

4 Errors found:
	Parameter "other" has no description
	Parameter "min_periods" description should finish with "."
	Return value has no description
	Return value has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

diff

Docstring for "pandas.core.series.Series.diff" correct. :)

append

6 Errors found:
	Parameter "to_append" has no description
	Parameter "ignore_index" type should use "bool" instead of "boolean"
	Parameter "verify_integrity" type should use "bool" instead of "boolean"
	Parameter "verify_integrity" description should finish with "."
	Return value has no description
	flake8 error: E231 missing whitespace after ',' (2 times)
1 Warnings found:
	No extended summary found

sort_index

Docstring for "pandas.core.series.Series.sort_index" correct. :)

argsort

4 Errors found:
	Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
	Summary should fit in a single line
	Parameter "kind" description should finish with "."
	Missing description for See Also "numpy.ndarray.argsort" reference
1 Warnings found:
	No examples section found

swaplevel

4 Errors found:
	Parameters {j, copy, i} not documented
	Unknown parameters {i, j}
	Parameter "i, j" type should use "str" instead of "string"
	Return value has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

unstack

7 Errors found:
	Summary should fit in a single line
	Parameter "level" type should use "str" instead of "string"
	Parameter "level" description should finish with "."
	Parameter "fill_value" description should start with a capital letter
	Parameter "fill_value" description should finish with "."
	Return value has no description
	flake8 error: E128 continuation line under-indented for visual indent
1 Warnings found:
	See Also section not found

rename

7 Errors found:
	Parameters {**kwargs} not documented
	Unknown parameters {level, inplace, copy}
	Parameter "index" description should start with a capital letter
	Parameter "copy" description should finish with "."
	Return value has no description
	Missing description for See Also "Series.rename_axis" reference
	flake8 error: E261 at least two spaces before inline comment

drop

4 Errors found:
	Parameters {columns, index} not documented
	Unknown parameters {index, columns}
	Return value has no description
	flake8 error: E231 missing whitespace after ',' (3 times)

isin

Docstring for "pandas.core.series.Series.isin" correct. :)

between

Docstring for "pandas.core.series.Series.between" correct. :)

from_csv

3 Errors found:
	Parameter "path" has no description
	Return value has no description
	Missing description for See Also "read_csv" reference
1 Warnings found:
	No examples section found

valid

2 Errors found:
	Parameters {inplace, **kwargs} not documented
	No Returns section found
2 Warnings found:
	See Also section not found
	No examples section found

to_period

2 Errors found:
	Summary should fit in a single line
	Parameters {copy} not documented
2 Warnings found:
	See Also section not found
	No examples section found

[dsaxton]

@WillAyd Side question, but when I merge with master on GitHub, how do I prevent lots of unrelated files from being marked as edited in my PR when I pull locally and then later push?

[WillAyd]

Typically I would do the below locally on branch in question

git fetch upstream
git merge upstream/master
<FIX CONFLICTS IF ANY, then git merge --continue>
git push origin your-branch-name

[jreback]

can you merge master

[WillAyd]

@dsaxton seeing some movement on this and maybe other PRs. Please ping when you are ready for review

[dsaxton]

@WillAyd Would be happy to have you take a look whenever you get a chance

[WillAyd]

Thanks - latest version looks like a good improvement over what was there previously. Can you provide updated script validations? Probably OK to leave a few out there for follow up PRs just want to make sure we haven't increased number of errors before approving

[dsaxton]

@WillAyd Still some errors / warnings here and there (some of which I don't think are real, others I'm not certain of the fix), but I think we've cleaned up a good chunk of them.

to_string

3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.to_string" correct. :)

to_dict

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.to_dict" correct. :)

to_frame

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.to_frame" correct. :)

to_sparse

2 Errors found:
	Parameter "kind" type should use "int" instead of "integer"
	Parameter "kind" has no description
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

count

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.count" correct. :)

mode

2 Warnings found:
	See Also section not found
	No examples section found
Docstring for "pandas.core.series.Series.mode" correct. :)

drop_duplicates

1 Errors found:
	Parameter "keep" description should start with a capital letter
1 Warnings found:
	No extended summary found

duplicated

1 Errors found:
	Parameter "keep" description should start with a capital letter

idxmin

2 Errors found:
	Parameters {**kwargs, *args} not documented
	Unknown parameters {*args, **kwargs}

idxmax

2 Errors found:
	Parameters {**kwargs, *args} not documented
	Unknown parameters {*args, **kwargs}

round

1 Errors found:
	Parameters {*args, **kwargs} not documented
1 Warnings found:
	No extended summary found

quantile

4 Errors found:
	Parameter "q" description should start with a capital letter
	Parameter "interpolation" has no description
	Missing description for See Also "core.window.Rolling.quantile" reference
	Missing description for See Also "numpy.percentile" reference
1 Warnings found:
	No extended summary found

corr

(flake8 is complaining about this code block, which I don't think is necessarily wrong.)

        >>> def histogram_intersection(a, b):
        ...     v = np.minimum(a, b).sum().round(decimals=1)
        ...     return v
        >>> s1 = pd.Series([.2, .0, .6, .2])
        >>> s2 = pd.Series([.3, .6, .0, .1])
        >>> s1.corr(s2, method=histogram_intersection)
        0.3

4 Errors found:
	Parameter "method" description should start with a capital letter
	Parameter "method" description should finish with "."
	flake8 error: E302 expected 2 blank lines, found 0
	flake8 error: E305 expected 2 blank lines after class or function definition, found 0
2 Warnings found:
	No extended summary found
	See Also section not found

cov

2 Warnings found:
	No extended summary found
	See Also section not found
Docstring for "pandas.core.series.Series.cov" correct. :)

diff

Docstring for "pandas.core.series.Series.diff" correct. :)

append

1 Warnings found:
	No extended summary found
Docstring for "pandas.core.series.Series.append" correct. :)

sort_index

Docstring for "pandas.core.series.Series.sort_index" correct. :)

argsort

4 Errors found:
	Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
	Summary should fit in a single line
	Parameter "kind" description should finish with "."
	Missing description for See Also "numpy.ndarray.argsort" reference
1 Warnings found:
	No examples section found

swaplevel

2 Errors found:
	Parameters {i, j, copy} not documented
	Unknown parameters {i, j}
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found

unstack

1 Errors found:
	Summary should fit in a single line
1 Warnings found:
	See Also section not found

rename

3 Errors found:
	Parameters {**kwargs} not documented
	Unknown parameters {level, copy, inplace}
	Parameter "index" description should start with a capital letter

drop

2 Errors found:
	Parameters {columns, index} not documented
	Unknown parameters {index, columns}

isin

Docstring for "pandas.core.series.Series.isin" correct. :)

between

Docstring for "pandas.core.series.Series.between" correct. :)

from_csv

3 Errors found:
	Parameter "path" has no description
	Return value has no description
	Missing description for See Also "read_csv" reference
1 Warnings found:
	No examples section found

valid

2 Errors found:
	Parameters {**kwargs, inplace} not documented
	No Returns section found
2 Warnings found:
	See Also section not found
	No examples section found

to_period

1 Errors found:
	Summary should fit in a single line
2 Warnings found:
	See Also section not found
	No examples section found

[WillAyd]

Makes sense. I checked most remaining and most are errors with the validator itself (ex: things that start with bullet points in description). I think this is a good enough improvement to move forward so we don't get stuck in a holding pattern forever.

cc @datapythonista - looks like there might be a new error for the below line, where 'integer' is a valid argument but the validator complains about it not being written out as int. I'll open up an issue for that separately

[WillAyd]

Thanks @dsaxton !