Examples for Series ops should be specific to each method.

[timgeb]

The code example for Series.divmod uses Series.add and I'm not sure what this is supposed to convey.

In addition, "Equivalent to series divmod other" and "See also: Series.None" look strange to me.

[dsaxton]

It looks to me like this is a larger problem with the Series operations documentation in general:

https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.gt.html
https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.lt.html
https://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.eq.html
...

In /pandas/core/ops.py it seems the Series.add example has been hard-coded for generic operations. Should there be separate examples for each?

[timgeb]

I think each method deserves an example.

[khizirsiddiqui]

Hi @timgeb !
If no one is assigned to this issue, I would want to work on this as my first issue.
Line 473 here hard-codes this.

[TomAugspurger]

Repurposing this for a general "fix all the Series ops examples".

It'd be helpful if someone could make a checklist on GitHub with all the Series ops (add, divmod, etc.) that need examples. And we can check them off as we go (one PR per op).

[danielplawrence]

Hi all, first contributor here

Looks like the list of affected cases is here

Checklist:

• pandas.Series.sub
• pandas.Series.mul
• pandas.Series.mod
• pandas.Series.pow
• pandas.Series.truediv
• pandas.Series.floordiv
• pandas.Series.divmod
• pandas.Series.eq
• pandas.Series.ne
• pandas.Series.lt
• pandas.Series.le
• pandas.Series.gt
• pandas.Series.ge

A quick script for comparing Series method docstring content: link

[danielplawrence]

So my understanding is that we will need to:

• Remove the examples under "Examples:" in __flex_doc_SERIES.
• Modify the _flex_doc_SERIES template and _make_flex_doc to allow injection of method-specific examples via str.format(). It looks like this was already implemented for dataframes in this revision
• Write examples for each method (e.g. _divmod_example_SERIES etc.) and add a key to _op_descriptions (e.g. 'series_examples') to be passed to _make_flex_doc and added to the output docstring.

[danielplawrence]

Opened initial PR here, please let me know if this approach makes sense. Do we have any guidelines for writing examples?