DOC: Prepare to add first docstrings checks to the CI

[datapythonista]

Fixing some docstring issues, so CI doesn't fail when we add the first validation of docstrings in #22854.

• closes #
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[pep8speaks]

Hello @datapythonista! Thanks for submitting the PR.

• 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/panel.py !

• There are no PEP8 issues in the file pandas/core/series.py !

[datapythonista]

These are the counts of errors of each category. This PR fixes and validates the first two:

Summary contains heading whitespaces	2
Do not import {imported_library}, as it is imported automatically for the examples (numpy as np, pandas as pd)	3
No Yields section found	6
Wrong parameters order. Actual: {actual_params}. Documented: {documented_params}	15
Parameter "{param_name}" type should not finish with "."	19
Private classes ({mentioned_private_classes}) should not be mentioned in public docstrings	32
Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")	58
Description should be capitalized for See Also "{reference_name}" reference	61
Parameter "{param_name}" has no type	61
No summary found (a short summary in a single line should be present at the beginning of the docstring)	92
Summary does not start with a capital letter	113
Missing period at end of description for See Also "{reference_name}" reference	164
No Returns section found	179
Examples do not pass tests:\n{doctest_log}	179
Parameter "{param_name}" description should start with a capital letter	188
{reference_name} in `See Also` section does not need `pandas` prefix, use {right_reference} instead.	204
Use only one blank line to separate sections or paragraphs	217
Unknown parameters {unknown_params}	224
Missing description for See Also "{reference_name}" reference	250
flake8 error: {error_code} {error_message}{times_happening}	275
Summary should fit in a single line	304
Parameter "{param_name}" has no description	353
Parameter "{param_name}" type should use "{right_type}" instead of "{wrong_type}"	396
Parameter "{param_name}" description should finish with "."	413
Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)	413
Parameters {missing_params} not documented	452
Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)	475
Summary does not end with a period	494

I'll create some "good first issues" once this is merged.

CC: @TomAugspurger @jorisvandenbossche

[jorisvandenbossche]

Cool!
Did you first try leaving an error to see what travis says?

[jorisvandenbossche]

Ah, actually, Travis is timing out on this ...

Should we maybe make one build just for all linting? (without running the actual test suite, to have a shorter build) Although you also have some work to move linting to Azure?

[datapythonista]

Yes, I'm still thinking what would be the best option, but I think running the code checks in an independent job will make things simpler in the CI files, and moving it to azure will make it easier for users to see the errors.

I think building the docs is quite slow too, but may be makes sense to have a job in azure for both, if it's not too long?

[jorisvandenbossche]

I think building the docs is quite slow too,

Yes, as long as it is on travis, we need to keep that separate (not add the linting to that), as this can already be quite long.

Depending on how far in the future the "moving linting to azure" is, I would maybe here simply move all linting to a new dedicated travis build.

[datapythonista]

Moving linting to azure is very close in the future: #22854. :)

I just want to think a bit more, if it makes sense to publish the artifacts of a build and save the resources of another conda setup and pandas build, or if that's too much complexity, and we should have an independent build for this.

I'd start by the simplest option and have an independent build, but azure was quite slow last days, and I didn't like adding the extra work. Auto-canceling the superseded builds in azure should be ready in the next hours (#23523 (comment)) so I think it's again the best option.

[codecov]

Codecov Report

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

@@            Coverage Diff             @@
##           master   #23560      +/-   ##
==========================================
- Coverage   92.25%   92.24%   -0.02%     
==========================================
  Files         161      161              
  Lines       51277    51278       +1     
==========================================
- Hits        47305    47299       -6     
- Misses       3972     3979       +7

Flag	Coverage Δ
#multiple	90.62% <ø> (-0.02%)	⬇️
#single	42.28% <ø> (-0.04%)	⬇️

Impacted Files	Coverage Δ
pandas/core/frame.py	97.03% <ø> (ø)	⬆️
pandas/core/series.py	93.7% <ø> (ø)	⬆️
pandas/core/generic.py	96.81% <ø> (ø)	⬆️
pandas/core/panel.py	97.91% <ø> (ø)	⬆️
pandas/util/testing.py	86.05% <0%> (-0.66%)	⬇️

---

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 b930303...9047183. Read the comment docs.

[datapythonista]

@jorisvandenbossche I'm leaving here the fixes to the docstrings, but I removed the validation of docstrings in the CI from this PR. So we avoid time outs with travis. Once this is merged, I'll add the validation to #22854.

[datapythonista]

@gfyoung if you don't mind taking a look at this one. Is similar to the one we just merged, #23600, but fixing other docstring errors.