DOC: Fix order of sections in Series docstrings

[datapythonista]

For consistency and to make our users life easier, we try to keep the same order of the sections in docstrings.

The right order of the sections is the defined by the numpydoc standard: https://numpydoc.readthedocs.io/en/latest/format.html#sections

Checking for errors in pandas Series attributes, we find many cases where the order is wrong:

$ ./scripts/validate_docstrings.py --prefix=pandas.Series --errors=GL07
pandas.Series.astype: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.infer_objects: Sections are in the wrong order. Correct order is: Returns, See Also, Examples
pandas.Series.convert_objects: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also
pandas.Series.at: Sections are in the wrong order. Correct order is: Raises, See Also, Examples
pandas.Series.iat: Sections are in the wrong order. Correct order is: Raises, See Also, Examples
pandas.Series.loc: Sections are in the wrong order. Correct order is: Raises, See Also, Examples
pandas.Series.add: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.sub: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.mul: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.div: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.truediv: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.floordiv: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.mod: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.pow: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.radd: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rsub: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rmul: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rdiv: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rtruediv: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rfloordiv: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rmod: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rpow: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.lt: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.gt: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.le: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.ge: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.ne: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.eq: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, 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.Series.rolling: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.expanding: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.ewm: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.pipe: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes
pandas.Series.abs: Sections are in the wrong order. Correct order is: Returns, See Also, Notes, Examples
pandas.Series.between: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.clip: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.cummax: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.cummin: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.cumprod: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.cumsum: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.nlargest: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.nsmallest: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.quantile: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.nonzero: Sections are in the wrong order. Correct order is: See Also, Examples
pandas.Series.drop: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Examples
pandas.Series.duplicated: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.first: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Examples
pandas.Series.idxmax: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Notes, Examples
pandas.Series.idxmin: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Notes, Examples
pandas.Series.last: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Examples
pandas.Series.reindex: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.where: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.mask: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.filter: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.fillna: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.argmin: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Notes, Examples
pandas.Series.argmax: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Notes, Examples
pandas.Series.unstack: Sections are in the wrong order. Correct order is: Parameters, Returns, Examples
pandas.Series.append: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.asfreq: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.asof: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.resample: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.at_time: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Examples
pandas.Series.between_time: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Examples
pandas.Series.tshift: Sections are in the wrong order. Correct order is: Parameters, Returns, Notes
pandas.Series.slice_shift: Sections are in the wrong order. Correct order is: Parameters, Returns, Notes
pandas.Series.dt.dayofweek: Sections are in the wrong order. Correct order is: Returns, See Also, Examples
pandas.Series.dt.weekday: Sections are in the wrong order. Correct order is: Returns, See Also, Examples
pandas.Series.dt.to_period: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Examples
pandas.Series.dt.to_pytimedelta: Sections are in the wrong order. Correct order is: Returns, See Also, Examples
pandas.Series.str.count: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.str.join: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes, Examples
pandas.Series.str.get_dummies: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.cat.rename_categories: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also, Examples
pandas.Series.cat.reorder_categories: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also
pandas.Series.cat.add_categories: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also
pandas.Series.cat.remove_categories: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also
pandas.Series.cat.set_categories: Sections are in the wrong order. Correct order is: Parameters, Returns, Raises, See Also
pandas.Series.to_excel: Sections are in the wrong order. Correct order is: Parameters, See Also, Notes, Examples
pandas.Series.to_xarray: Sections are in the wrong order. Correct order is: Returns, See Also, Notes, Examples
pandas.Series.as_matrix: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Notes
pandas.Series.divide: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.divmod: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.from_csv: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also
pandas.Series.multiply: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.rdivmod: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples
pandas.Series.subtract: Sections are in the wrong order. Correct order is: Parameters, Returns, See Also, Examples

We should change the order of the sections in these methods, so the call to the script doesn't report any error.

[YuechengWu]

Hi, I would like to work on this if it's ok, thanks.

[datapythonista]

Thank you @YuechengWu, that's great. Let me know if you need help.

And feel free to do it in more than one PR if you think it's too much for a single one (I think many of the items in the list reuse the same docstring, so the changes shouldn't be as long as they may look).

[YuechengWu]

@datapythonista Thanks.

[YuechengWu]

@datapythonista Hi Marc, do I use the command line to test for the errors? or can I still use Anaconda to test it?

[datapythonista]

You should have a development environment. Instructions to set it up are here: https://python-sprints.github.io/pandas/guide/pandas_setup.html#instructions

Then, in the command line (or Anaconda prompt) with the pandas-dev environment active, you should be able to run the command in the description from the root of the project.

[YuechengWu]

@datapythonista Hi Marc, when I run the command, it tells me '.' is not recognized as an internal or external command. I believe my environment is setup correctly.

[datapythonista]

Can you copy here what you are running and what you are getting. Not sure if you have a space after the period, or something like that. But can't really tell without a screenshot or a copy of what you are running.

[YuechengWu]

@datapythonista This is what I am getting

[datapythonista]

Sorry, couldn't see the image in my mobile. I guess this is windows, I don't know much about it, can you try without the ./ (so, scripts/validate_docstrings.py --prefix=pandas.Series --errors=GL07).

Or try to cd scripts and then just validate_docstrings.py --prefix=pandas.Series --errors=GL07

[datapythonista]

Sorry @YuechengWu, seems like this issue has been addressed in #24126. Not sure if you could make any progress, but not worth working on it anymore.

Closing as duplicate, as the other issue has been created for all the errors, not only the ones in Series.