Skip to content
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

Examples for Series ops should be specific to each method. #24589

Closed
timgeb opened this issue Jan 3, 2019 · 12 comments · Fixed by #37185
Closed

Examples for Series ops should be specific to each method. #24589

timgeb opened this issue Jan 3, 2019 · 12 comments · Fixed by #37185
Labels
Docs good first issue

Comments

@timgeb
Copy link

timgeb commented Jan 3, 2019 •
edited
Loading

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

dsaxton commented Jan 3, 2019 •
edited
Loading

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

timgeb commented Jan 3, 2019

I think each method deserves an example.

@khizirsiddiqui
Copy link

khizirsiddiqui commented Jan 14, 2019 •
edited
Loading

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.

@mroeschke mroeschke mentioned this issue Jan 18, 2019
Closed
@TomAugspurger TomAugspurger mentioned this issue Feb 13, 2019
Closed
@TomAugspurger TomAugspurger changed the title The documentation example for Series.divmod does not use Series.divmod. Examples for Series ops should be specific to each method. Feb 13, 2019
@TomAugspurger
Copy link
Contributor

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

Hi all, first contributor here

Looks like the list of affected cases is here

Checklist:

A quick script for comparing Series method docstring content: link

@danielplawrence
Copy link
Contributor

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 added a commit to danielplawrence/pandas that referenced this issue Mar 3, 2019
@danielplawrence
DOC:Remove hard-coded example from _flex_doc_SERIES and allow _make_f…
650eb4f 
…lex_doc to inject examples from _op_desc (pandas-dev#24589)
danielplawrence added a commit to danielplawrence/pandas that referenced this issue Mar 3, 2019
@danielplawrence
DOC:Remove hard-coded examples from _flex_doc_SERIES (pandas-dev#24589)
2f6173c
@danielplawrence danielplawrence mentioned this issue Mar 3, 2019
Merged
@danielplawrence
Copy link
Contributor

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

danielplawrence added a commit to danielplawrence/pandas that referenced this issue Mar 4, 2019
@danielplawrence
DOC:Add fill_value to example for SERIES.multiply() (pandas-dev#24589)
658ea82
danielplawrence added a commit to danielplawrence/pandas that referenced this issue Mar 4, 2019
@danielplawrence
DOC:Add examples for SERIES ops -- mod,pow,truediv,floordiv (pandas-d…
adce628 
…ev#24589)
danielplawrence added a commit to danielplawrence/pandas that referenced this issue Mar 4, 2019
@danielplawrence
DOC:Use string concatenation in _make_flex_doc to appease docstring v…
fc60c5f 
…alidator (pandas-dev#24589)
danielplawrence added a commit to danielplawrence/pandas that referenced this issue Mar 4, 2019
@danielplawrence
DOC:Fix a long line to satisfy PEP8 (pandas-dev#24589)
74d47c6
danielplawrence added a commit to danielplawrence/pandas that referenced this issue Mar 5, 2019
@danielplawrence
DOC: break out _make_flex_doc format arguments on seperate lines (pan…
6d7ed91 
…das-dev#24589)
TomAugspurger pushed a commit that referenced this issue Mar 11, 2019
@danielplawrence @TomAugspurger
DOC:Remove hard-coded examples from _flex_doc_SERIES (#24589) (#25524)
3099773 
* DOC:Remove hard-coded examples from _flex_doc_SERIES (#24589)
thoo added a commit to thoo/pandas that referenced this issue Mar 11, 2019
@thoo
Merge remote-tracking branch 'upstream/master' into pivot
aaa21bb 
* upstream/master: (110 commits)
  DOC: hardcode contributors for 0.24.x releases (pandas-dev#25662)
  DOC: restore toctree maxdepth (pandas-dev#25134)
  BUG: Redefine IndexOpsMixin.size, fix pandas-dev#25580. (pandas-dev#25584)
  BUG: to_csv line endings with compression (pandas-dev#25625)
  DOC: file obj for to_csv must be newline='' (pandas-dev#25624)
  Suppress incorrect warning in nargsort for timezone-aware DatetimeIndex (pandas-dev#25629)
  TST: fix incorrect sparse test (now failing on scipy master) (pandas-dev#25653)
  CLN: Removed debugging code (pandas-dev#25647)
  DOC: require Return section only if return is not None nor commentary (pandas-dev#25008)
  DOC:Remove hard-coded examples from _flex_doc_SERIES (pandas-dev#24589) (pandas-dev#25524)
  TST: xref pandas-dev#25630 (pandas-dev#25643)
  BUG: Fix pandas-dev#25481 by fixing the error message in TypeError (pandas-dev#25540)
  Fixturize tests/frame/test_mutate_columns.py (pandas-dev#25642)
  Fixturize tests/frame/test_join.py (pandas-dev#25639)
  Fixturize tests/frame/test_combine_concat.py (pandas-dev#25634)
  Fixturize tests/frame/test_asof.py (pandas-dev#25628)
  BUG: Fix user-facing AssertionError with to_html (pandas-dev#25608) (pandas-dev#25620)
  DOC: resolve all GL03 docstring validation errors (pandas-dev#25525)
  TST: failing wheel building on PY2 and old numpy (pandas-dev#25631)
  DOC: Remove makePanel from docs (pandas-dev#25609) (pandas-dev#25612)
  ...
@TomAugspurger TomAugspurger mentioned this issue Jun 20, 2019
Closed
@RanDan363
Copy link

Hi all, first timer here.
would love to give a hand,
where can I see what needs to be done?

@TomAugspurger
Copy link
Contributor

#25524 may give some insight. That did add and sub.

pandas/pandas/core/ops/docstrings.py

Line 236 in 045880c

_op_descriptions = {
has the list. Items there where df_examples is None need to be updated.

@avimiller
Copy link

I would like to add series examples for "gt", "lt", and "eq" if that is okay.

sullivanbt added a commit to sullivanbt/pandas that referenced this issue Mar 14, 2020
@sullivanbt
DOC: add series examples (pandas-dev#24589)
e828f24 
adds documentation example to:
- `pandas.Series.eq`
- `pandas.Series.ne`
- `pandas.Series.gt`,
- `pandas.Series.ge`
- `pandas.series.le`
- `pandas.series.lt`
@sullivanbt sullivanbt mentioned this issue Mar 14, 2020
Merged
TomAugspurger pushed a commit that referenced this issue Mar 24, 2020
@sullivanbt
DOC: Add examples to Series operators (#24589) (#32704)
08fce67 
* DOC: add series examples (#24589)

adds documentation example to:
- `pandas.Series.eq`
- `pandas.Series.ne`
- `pandas.Series.gt`,
- `pandas.Series.ge`
- `pandas.series.le`
- `pandas.series.lt`
@TomAugspurger
Copy link
Contributor

@sullivanbt after #32704, is divmod the only one remaining?

@sullivanbt
Copy link
Contributor

@TomAugspurger Yes, divmod was the only one remaining after #32704

@hongshaoyang hongshaoyang mentioned this issue Oct 17, 2020
Merged
4 tasks
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

Successfully merging a pull request may close this issue.

DOC: Add example to Series.divmod hongshaoyang/pandas
9 participants
@TomAugspurger @dsaxton @timgeb @danielplawrence @mroeschke @khizirsiddiqui @avimiller @sullivanbt @RanDan363