Skip to content

DOC: Fix order of sections in Series docstrings #24058

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
datapythonista opened this issue Dec 3, 2018 · 11 comments
Closed

DOC: Fix order of sections in Series docstrings #24058

datapythonista opened this issue Dec 3, 2018 · 11 comments
Labels
Docs good first issue

Comments

@datapythonista
Copy link
Member

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
Copy link
Contributor

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

@datapythonista
Copy link
Member Author

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
Copy link
Contributor

@datapythonista Thanks.

@YuechengWu
Copy link
Contributor

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

@datapythonista
Copy link
Member Author

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
Copy link
Contributor

@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
Copy link
Member Author

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
Copy link
Contributor

image

@datapythonista This is what I am getting

@datapythonista
Copy link
Member Author

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 datapythonista mentioned this issue Dec 6, 2018
Closed
@datapythonista
Copy link
Member Author

datapythonista commented Dec 6, 2018 •
edited
Loading

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.

@YuechengWu
Copy link
Contributor

@datapythonista ok, thanks for letting me know

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Docs good first issue
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@datapythonista @YuechengWu