DOC: Fix docstrings error GL07 - Sections are in the wrong order

[alexander-ponomaroff]

When checking for errors with ./scripts/validate_docstrings.py, There is an error that comes up:

GL07
'Sections are in the wrong order. Correct order is: ' '{correct_sections}'

I worked on this and will create a pull request for this issue shortly to go into more detail on what I fixed.

@datapythonista

[datapythonista]

We had an other issue for part of them: #24058

I don't think there was so much progress, but it's better to check before to avoid duplicate work.

[alexander-ponomaroff]

Sorry about that, I didn't notice issue #24058 when I was fixing all the GL07 errors. @YuechengWu I will try to find you another similar error to work on today.

[YuechengWu]

@alexander-ponomaroff no worries, I wasn't making much progress, what other similar errors there are? Let me know if you find anything. Thank you.

[alexander-ponomaroff]

Once #24126 gets merged. I will make a pull request that fixes an additional 10 out of 24 remaining errors. The remaining 14 errors are a bit problematic and need to be addressed. I will post the remaining 14 errors below and the problems with them.

These 4 errors have similar problems - appending a template to its own docs

pandas.core.groupby.GroupBy.head: Sections are in the wrong order. Correct order is: See Also, Examples
pandas.core.groupby.GroupBy.mean: Sections are in the wrong order. Correct order is: Returns, See Also, Examples
pandas.core.groupby.GroupBy.nth: Sections are in the wrong order. Correct order is: Parameters, See Also, Examples
pandas.core.groupby.GroupBy.tail: Sections are in the wrong order. Correct order is: See Also, Examples

EXAMPLE

@Appender(_doc_template)
    def head(self, n=5):
        """
        Returns first n rows of each group.

        Essentially equivalent to ``.apply(lambda x: x.head(n))``,
        except ignores as_index flag.

        Examples
        --------

        >>> df = pd.DataFrame([[1, 2], [1, 4], [5, 6]],
                              columns=['A', 'B'])
        >>> df.groupby('A', as_index=False).head(1)
           A  B
        0  1  2
        2  5  6
        >>> df.groupby('A').head(1)
           A  B
        0  1  2
        2  5  6
        """

These 9 errors have similar problems - appending two different docs

pandas.core.resample.Resampler.apply: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.core.resample.Resampler.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.core.groupby.DataFrameGroupBy.agg: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.core.window.Rolling.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.core.window.Expanding.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.agg: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.DataFrame.agg: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.DataFrame.aggregate: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples

EXAMPLE

    @Appender(_agg_doc)
    @Appender(_shared_docs['aggregate']

Unable to trace where this error occurs - mean() from GroupBy has proper order of docs

pandas.core.resample.Resampler.mean: Sections are in the wrong order. Correct order is: Returns, See Also, Examples

[alexander-ponomaroff]

@YuechengWu I found something that you can explore and work on if you'd like. Sorry again for accidentally taking some of the errors that you started exploring.

If you run the following command:
./scripts/validate_docstrings.py --errors=SS03 --format=azure | grep 'pandas/core/generic.py'

You will get all SS03 errors in the pandas/core/generic.py file. There are many of these errors in that file. (SS03 - Summary does not end with a period)

It will be easier for you to start in one file and go from there. Running ./scripts/validate_docstrings.py --errors=SS03 will give you all the SS03 errors in Pandas. --format=azure will allow you to see files and line numbers where the error occurs. | grep 'pandas/core/generic.py' will filter all the errors and will just output the errors from the 'pandas/core/generic.py' file. Once you get some practice in generic.py file, you can continue with this error in other files.

If you are interested in this error, please create an issue similarly to how I created this one (maybe with some screenshots to make it better 👍). And create a pull request for that issue. Make sure to let people know in the issue that you are already working on this.

[YuechengWu]

@alexander-ponomaroff hey Alex, when I run the script, it tells me grep is not recognized as an internal or external command. Then I ran the script with out the pipe part, it has given me a bunch of errors, here is the screen shot, let me know if you can see this. Thanks.

[datapythonista]

grep only works on linux/mac. You can add --prefix=pandas.Series. and it will also return a subset you can work with

[YuechengWu]

@alexander-ponomaroff @datapythonista are these errors I am suppose to get after running the script? Let me know if you guys are able to see it. Thanks.

[datapythonista]

yes, that looks good. Do we have an issue for it? would be nice to keep the conversarion in the corresponding issue, this one is unrelated to this, right?

[YuechengWu]

@datapythonista not yet, i am going to create an issue and work on it if that's ok

[datapythonista]

sure, that sounds great.