DOC: Fix docstrings with the sections in the wrong order #24280 #24288

benjaminr · 2018-12-15T00:02:27Z

closes DOC: Fix docstrings with the sections in the wrong order #24280
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff

…4280

pep8speaks · 2018-12-15T00:02:46Z

Hello @benjaminr! Thanks for updating the PR.

There are no PEP8 issues in the file pandas/core/accessor.py !
There are no PEP8 issues in the file pandas/core/frame.py !
There are no PEP8 issues in the file pandas/core/generic.py !
There are no PEP8 issues in the file pandas/core/groupby/generic.py !
There are no PEP8 issues in the file pandas/core/groupby/groupby.py !
There are no PEP8 issues in the file pandas/core/resample.py !
There are no PEP8 issues in the file pandas/core/series.py !
There are no PEP8 issues in the file pandas/core/window.py !

Comment last updated on December 15, 2018 at 23:46 Hours UTC

datapythonista

Thanks for fixing these @benjaminr

Can you add the validation of the error to ci/code_checks.sh. It's explained in the issue description.

pandas/core/groupby/groupby.py

pandas/core/window.py

codecov · 2018-12-15T23:38:27Z

Codecov Report

Merging #24288 into master will decrease coverage by 49.21%.
The diff coverage is 100%.

@@             Coverage Diff             @@
##           master   #24288       +/-   ##
===========================================
- Coverage   92.22%   43.01%   -49.22%     
===========================================
  Files         162      162               
  Lines       51824    51820        -4     
===========================================
- Hits        47795    22288    -25507     
- Misses       4029    29532    +25503

Flag	Coverage Δ
#multiple	`?`
#single	`43.01% <100%> (-0.01%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/accessor.py	`63.85% <ø> (-34.94%)`	⬇️
pandas/core/window.py	`28.93% <100%> (-67.47%)`	⬇️
pandas/core/groupby/groupby.py	`24.5% <100%> (-72.17%)`	⬇️
pandas/core/resample.py	`22.73% <100%> (-73.85%)`	⬇️
pandas/core/frame.py	`35.88% <100%> (-61.03%)`	⬇️
pandas/core/groupby/generic.py	`13.5% <100%> (-73.63%)`	⬇️
pandas/core/series.py	`49.32% <100%> (-44.38%)`	⬇️
pandas/io/formats/latex.py	`0% <0%> (-100%)`	⬇️
pandas/core/categorical.py	`0% <0%> (-100%)`	⬇️
pandas/io/sas/sas_constants.py	`0% <0%> (-100%)`	⬇️
... and 126 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 7b0fa8e...fd54af4. Read the comment docs.

codecov · 2018-12-15T23:38:27Z

Codecov Report

Merging #24288 into master will increase coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #24288      +/-   ##
==========================================
+ Coverage   92.28%   92.28%   +<.01%     
==========================================
  Files         162      162              
  Lines       51831    51837       +6     
==========================================
+ Hits        47830    47837       +7     
+ Misses       4001     4000       -1

Flag	Coverage Δ
#multiple	`90.68% <100%> (ø)`	⬆️
#single	`43% <100%> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/window.py	`96.41% <100%> (+0.01%)`	⬆️
pandas/core/groupby/generic.py	`87.15% <100%> (+0.03%)`	⬆️
pandas/core/series.py	`93.71% <100%> (ø)`	⬆️
pandas/core/groupby/groupby.py	`96.65% <100%> (-0.03%)`	⬇️
pandas/core/resample.py	`96.58% <100%> (ø)`	⬆️
pandas/core/frame.py	`96.91% <100%> (ø)`	⬆️
pandas/core/generic.py	`96.66% <100%> (ø)`	⬆️
pandas/util/testing.py	`87.58% <0%> (+0.09%)`	⬆️

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 216986d...fc5fc69. Read the comment docs.

datapythonista

can you add to ci/code_checks.sh the validation of GL07 in the call to scripts/validate_docstrings.py, so we can see that everything is correct now?

pandas/core/groupby/groupby.py

datapythonista · 2018-12-16T01:57:17Z

Also, the errors in the CI are because there is a test comparing that the common methods of NaT and Timestamp have the same docstrings. You can see a fix to a failure in this same test here: 5c54db8

If you try to reproduce the test failure locally, note that .pyx needs to be compiled for the right docstrings to be accessed.

datapythonista · 2018-12-16T02:10:41Z

Can you merge master too. We just merged #24132, and with this PR, all the sections should be in the right order now. When you add the check to ci/code_checks.sh we'll be sure.

…tution decorator in docstrings where commonly repeated

…ugh aggregate method docstrings still have the issue of sharing a docstring with Notes directly after Returns. This means any further appends with a See Also section are out of order.

datapythonista · 2018-12-17T00:02:56Z

We've got this cases failing in the CI:

2018-12-16T17:17:04.7332443Z ##[error]pandas/core/series.py(3305,): error GL07: pandas.Series.agg: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7343114Z ##[error]pandas/core/series.py(3305,): error GL07: pandas.Series.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7345657Z ##[error]pandas/core/frame.py(6094,): error GL07: pandas.DataFrame.agg: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7346376Z ##[error]pandas/core/frame.py(6094,): error GL07: pandas.DataFrame.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7347044Z ##[error]pandas/core/window.py(1648,): error GL07: pandas.core.window.Rolling.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7347714Z ##[error]pandas/core/window.py(1924,): error GL07: pandas.core.window.Expanding.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7348542Z ##[error]pandas/core/groupby/generic.py(1305,): error GL07: pandas.core.groupby.DataFrameGroupBy.agg: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7349265Z ##[error]pandas/core/resample.py(256,): error GL07: pandas.core.resample.Resampler.apply: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
2018-12-16T17:17:04.7350194Z ##[error]pandas/core/resample.py(256,): error GL07: pandas.core.resample.Resampler.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples

If they can't be fixed with the Appender the way it is, we may have to split what we are appending, of just generate the string with .format()... Do you think you can do it?

… order right.

datapythonista

looks good, just couple of comments

pandas/core/frame.py

ci/code_checks.sh

pandas/core/series.py

pandas/core/window.py

datapythonista

Looks really good, much better now. Just two small details, and let's see how the CI finishes, and this should be ready to be merged.

pandas/core/frame.py

pandas/core/groupby/generic.py

…cstrings.

…summary.

datapythonista

lgtm, thanks a lot for this @benjaminr, nice fixes

benjaminr · 2018-12-19T11:39:21Z

No problem, thanks for your patience @datapythonista :)

jreback · 2018-12-19T12:32:59Z

thanks @benjaminr

…4280 (pandas-dev#24288)

benjaminr added 3 commits December 14, 2018 23:34

DOC: Fix docstrings with the sections in the wrong order pandas-dev#2…

4446942

…4280

DOC: Fix docstrings with the sections in the wrong order pandas-dev#2…

baa2950

…4280

Removal of whitespace to satisfy flak8 checks.

c73c5f0

datapythonista reviewed Dec 15, 2018

View reviewed changes

pandas/core/groupby/groupby.py Outdated Show resolved Hide resolved

pandas/core/window.py Show resolved Hide resolved

jreback added the Docs label Dec 15, 2018

benjaminr force-pushed the master branch from fbb63b3 to c73c5f0 Compare December 16, 2018 00:06

datapythonista reviewed Dec 16, 2018

View reviewed changes

pandas/core/groupby/groupby.py Outdated Show resolved Hide resolved

datapythonista mentioned this pull request Dec 16, 2018

DOC: Fix order section in docstrings (part II) #24132

Merged

2 tasks

benjaminr added 4 commits December 16, 2018 15:35

Merge branch 'master' of https://github.com/pandas-dev/pandas

c042341

Refactored _doc_template to _common_see_also and used with the substi…

14fe729

…tution decorator in docstrings where commonly repeated

Updated CI checks to include GL07 docstring validation.

23350de

Docstring appends were in the wrong order - this corrects that. Altho…

3d18f6b

…ugh aggregate method docstrings still have the issue of sharing a docstring with Notes directly after Returns. This means any further appends with a See Also section are out of order.

benjaminr added 2 commits December 17, 2018 18:32

Use of format on _shared_docs['aggregate'] docstring usage to get the…

a1db80b

… order right.

Merge branch 'master' of https://github.com/pandas-dev/pandas

faac16d

datapythonista reviewed Dec 18, 2018

View reviewed changes

pandas/core/frame.py Outdated Show resolved Hide resolved

ci/code_checks.sh Outdated Show resolved Hide resolved

pandas/core/series.py Outdated Show resolved Hide resolved

pandas/core/window.py Outdated Show resolved Hide resolved

pandas/core/window.py Outdated Show resolved Hide resolved

benjaminr added 3 commits December 18, 2018 10:07

Merge branch 'master' of https://github.com/pandas-dev/pandas

0a7ed6d

Updated to code check order and included GL07 in messages.

64af1fc

Use of substitution to clean up docstring order fix.

3e54918

datapythonista reviewed Dec 18, 2018

View reviewed changes

pandas/core/frame.py Outdated Show resolved Hide resolved

pandas/core/groupby/generic.py Outdated Show resolved Hide resolved

benjaminr added 3 commits December 18, 2018 10:40

Corrected order of see_also and examples string defitions to match do…

5f64fcf

…cstrings.

Updated name of _agg_see_also_doc to reflect fact it also contains a …

bdeb8ae

…summary.

Fix added import statement to be in the correct order.

fc5fc69

datapythonista approved these changes Dec 19, 2018

View reviewed changes

jreback added this to the 0.24.0 milestone Dec 19, 2018

jreback merged commit 312a8ee into pandas-dev:master Dec 19, 2018

TomAugspurger pushed a commit to TomAugspurger/pandas that referenced this pull request Dec 20, 2018

DOC: Fix docstrings with the sections in the wrong order pandas-dev#2…

8db2167

…4280 (pandas-dev#24288)

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

DOC: Fix docstrings with the sections in the wrong order pandas-dev#2…

e93dd50

…4280 (pandas-dev#24288)

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

DOC: Fix docstrings with the sections in the wrong order pandas-dev#2…

c3cabf0

…4280 (pandas-dev#24288)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Fix docstrings with the sections in the wrong order #24280 #24288

DOC: Fix docstrings with the sections in the wrong order #24280 #24288

benjaminr commented Dec 15, 2018 •

edited by datapythonista

Loading

pep8speaks commented Dec 15, 2018 •

edited

Loading

datapythonista left a comment

codecov bot commented Dec 15, 2018

codecov bot commented Dec 15, 2018 •

edited

Loading

datapythonista left a comment

datapythonista commented Dec 16, 2018

datapythonista commented Dec 16, 2018

datapythonista commented Dec 17, 2018

datapythonista left a comment

datapythonista left a comment

datapythonista left a comment

benjaminr commented Dec 19, 2018

jreback commented Dec 19, 2018

DOC: Fix docstrings with the sections in the wrong order #24280 #24288

DOC: Fix docstrings with the sections in the wrong order #24280 #24288

Conversation

benjaminr commented Dec 15, 2018 • edited by datapythonista Loading

pep8speaks commented Dec 15, 2018 • edited Loading

Comment last updated on December 15, 2018 at 23:46 Hours UTC

datapythonista left a comment

Choose a reason for hiding this comment

codecov bot commented Dec 15, 2018

Codecov Report

codecov bot commented Dec 15, 2018 • edited Loading

Codecov Report

datapythonista left a comment

Choose a reason for hiding this comment

datapythonista commented Dec 16, 2018

datapythonista commented Dec 16, 2018

datapythonista commented Dec 17, 2018

datapythonista left a comment

Choose a reason for hiding this comment

datapythonista left a comment

Choose a reason for hiding this comment

datapythonista left a comment

Choose a reason for hiding this comment

benjaminr commented Dec 19, 2018

jreback commented Dec 19, 2018

benjaminr commented Dec 15, 2018 •

edited by datapythonista

Loading

pep8speaks commented Dec 15, 2018 •

edited

Loading

codecov bot commented Dec 15, 2018 •

edited

Loading