DOC: Updating operators docstrings #20415
- Loading branch information
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -398,166 +398,166 @@ def _get_op_name(op, special): | |
| """ | ||
|
|
||
| _eq_example_FRAME = """ | ||
| >>> df1 = pd.DataFrame({'company': ['A', 'B', 'C'], | ||
| ... 'cost': [250, 150, 100], | ||
| ... 'revenue': [100, 250, 300]}) | ||
| >>> df1 | ||
| company cost revenue | ||
| 0 A 250 100 | ||
| 1 B 150 250 | ||
| 2 C 100 300 | ||
| >>> df2 = pd.DataFrame({'company': ['A', 'B', 'C', 'D'], | ||
| ... 'revenue': [300, 250, 100, 150]}) | ||
| >>> df2 | ||
| company revenue | ||
| 0 A 300 | ||
| 1 B 250 | ||
| 2 C 100 | ||
| 3 D 150 | ||
| >>> df1.eq(df2) | ||
| company cost revenue | ||
| 0 True False False | ||
| 1 True False True | ||
| 2 True False False | ||
| 3 False False False | ||
| """ | ||
|
|
||
| _ne_example_FRAME = """ | ||
| >>> df1 = pd.DataFrame({'company': ['A', 'B', 'C'], | ||
| ... 'cost': [250, 150, 100], | ||
| ... 'revenue': [100, 250, 300]}) | ||
| >>> df1 | ||
| company cost revenue | ||
| 0 A 250 100 | ||
| 1 B 150 250 | ||
| 2 C 100 300 | ||
| >>> df2 = pd.DataFrame({'company': ['A', 'B', 'C', 'D'], | ||
| ... 'revenue': [300, 250, 100, 150]}) | ||
| >>> df2 | ||
| company revenue | ||
| 0 A 300 | ||
| 1 B 250 | ||
| 2 C 100 | ||
| 3 D 150 | ||
| >>> df1.ne(df2) | ||
| company cost revenue | ||
| 0 False True True | ||
| 1 False True False | ||
| 2 False True True | ||
| 3 True True True | ||
| """ | ||
|
|
||
| _lt_example_FRAME = """ | ||
| >>> df1 = pd.DataFrame({'company': ['A', 'B', 'C'], | ||
| ... 'cost': [250, 150, 100], | ||
| ... 'revenue': [100, 250, 300]}) | ||
| >>> df1 | ||
| company cost revenue | ||
| 0 A 250 100 | ||
| 1 B 150 250 | ||
| 2 C 100 300 | ||
| >>> df2 = pd.DataFrame({'company': ['A', 'B', 'C', 'D'], | ||
| ... 'revenue': [300, 250, 100, 150]}) | ||
| >>> df2 | ||
| company revenue | ||
| 0 A 300 | ||
| 1 B 250 | ||
| 2 C 100 | ||
| 3 D 150 | ||
| >>> df1.lt(df2) | ||
| company cost revenue | ||
| 0 False False True | ||
| 1 False False False | ||
| 2 False False False | ||
| 3 False False False | ||
| """ | ||
|
|
||
| _le_example_FRAME = """ | ||
| >>> df1 = pd.DataFrame({'company': ['A', 'B', 'C'], | ||
| ... 'cost': [250, 150, 100], | ||
| ... 'revenue': [100, 250, 300]}) | ||
| >>> df1 | ||
| company cost revenue | ||
| 0 A 250 100 | ||
| 1 B 150 250 | ||
| 2 C 100 300 | ||
| >>> df2 = pd.DataFrame({'company': ['A', 'B', 'C', 'D'], | ||
| ... 'revenue': [300, 250, 100, 150]}) | ||
| >>> df2 | ||
| company revenue | ||
| 0 A 300 | ||
| 1 B 250 | ||
| 2 C 100 | ||
| 3 D 150 | ||
| >>> df1.le(df2) | ||
| company cost revenue | ||
| 0 True False True | ||
| 1 True False True | ||
| 2 True False False | ||
| 3 False False False | ||
| """ | ||
|
|
||
| _gt_example_FRAME = """ | ||
| >>> df1 = pd.DataFrame({'company': ['A', 'B', 'C'], | ||
| ... 'cost': [250, 150, 100], | ||
| ... 'revenue': [100, 250, 300]}) | ||
| >>> df1 | ||
| company cost revenue | ||
| 0 A 250 100 | ||
| 1 B 150 250 | ||
| 2 C 100 300 | ||
| >>> df2 = pd.DataFrame({'company': ['A', 'B', 'C', 'D'], | ||
| ... 'revenue': [300, 250, 100, 150]}) | ||
| >>> df2 | ||
| company revenue | ||
| 0 A 300 | ||
| 1 B 250 | ||
| 2 C 100 | ||
| 3 D 150 | ||
| >>> df1.gt(df2) | ||
| company cost revenue | ||
| 0 False False False | ||
| 1 False False False | ||
| 2 False False True | ||
| 3 False False False | ||
| """ | ||
|
|
||
| _ge_example_FRAME = """ | ||
| >>> df1 = pd.DataFrame({'company': ['A', 'B', 'C'], | ||
| ... 'cost': [250, 150, 100], | ||
| ... 'revenue': [100, 250, 300]}) | ||
| >>> df1 | ||
| company cost revenue | ||
| 0 A 250 100 | ||
| 1 B 150 250 | ||
| 2 C 100 300 | ||
| >>> df2 = pd.DataFrame({'company': ['A', 'B', 'C', 'D'], | ||
| ... 'revenue': [300, 250, 100, 150]}) | ||
| >>> df2 | ||
| company revenue | ||
| 0 A 300 | ||
| 1 B 250 | ||
| 2 C 100 | ||
| 3 D 150 | ||
| >>> df1.ge(df2) | ||
| company cost revenue | ||
| 0 True False False | ||
| 1 True False True | ||
| 2 True False True | ||
| 3 False False False | ||
| """ | ||
|
|
||
| _comp_others = """ | ||
| DataFrame.eq : Compare DataFrames for equality elementwise | ||
| DataFrame.ne : Compare DataFrames for inequality elementwise | ||
| DataFrame.le : Compare DataFrames for less than inequality | ||
| or equality elementwise | ||
| DataFrame.lt : Compare DataFrames for strictly less than | ||
| inequality elementwise | ||
| DataFrame.ge : Compare DataFrames for greater than inequality | ||
| or equality elementwise | ||
| DataFrame.gt : Compare DataFrames for strictly greater than | ||
| inequality elementwise | ||
| """ | ||
|
|
||
| _op_descriptions = { | ||
|
|
@@ -598,17 +598,17 @@ def _get_op_name(op, special): | |
| # Comparison Operators | ||
| 'eq': {'op': '==', | ||
| 'desc': 'Equal to', | ||
| 'reverse': None, | ||
| 'df_examples': _eq_example_FRAME, | ||
| 'others': _comp_others}, | ||
| 'ne': {'op': '!=', | ||
| 'desc': 'Not equal to', | ||
| 'reverse': None, | ||
| 'df_examples': _ne_example_FRAME, | ||
| 'others': _comp_others}, | ||
| 'lt': {'op': '<', | ||
| 'desc': 'Less than', | ||
| 'reverse': None, | ||
| 'df_examples': _lt_example_FRAME, | ||
| 'others': _comp_others}, | ||
| 'le': {'op': '<=', | ||
|
|
@@ -618,12 +618,12 @@ def _get_op_name(op, special): | |
| 'others': _comp_others}, | ||
| 'gt': {'op': '>', | ||
| 'desc': 'Greater than', | ||
| 'reverse': None, | ||
| 'df_examples': _gt_example_FRAME, | ||
| 'others': _comp_others}, | ||
| 'ge': {'op': '>=', | ||
| 'desc': 'Greater than or equal to', | ||
| 'reverse': None, | ||
| 'df_examples': _ge_example_FRAME, | ||
| 'others': _comp_others}} | ||
|
|
||
|
|
@@ -754,30 +754,36 @@ def _get_op_name(op, special): | |
| _flex_comp_doc_FRAME = """ | ||
| Flexible wrappers to comparison operators (specifically ``{name}``). | ||
|
|
||
| Equivalent to `==`, `=!`, `<=`, `<`, `>=`, `>` with support to choose | ||
|
There was a problem hiding this comment. I'm a bit confused... In the previous dictionaries, you define There was a problem hiding this comment. To be consistent with examples that run through several of these sibling methods, the intro lists all of them. It seems counterintuitive to have an intro that describes one method with examples from several methods. |
||
| axis (rows or columns) for comparison. | ||
|
|
||
| Parameters | ||
| ---------- | ||
| other : DataFrame | ||
| Any structured DataFrame. Can be different number of columns or rows. | ||
| axis : int or str, optional | ||
| Axis to target. Can be either the axis name ('index', 'rows', | ||
| 'columns') or number (0, 1). | ||
|
There was a problem hiding this comment. To be consistent, I'd document the axis as we usually do. See this docstring: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.drop.html |
||
| level : int or name | ||
|
There was a problem hiding this comment. Better to use |
||
| Broadcast across a level, matching Index values on the passed | ||
| MultiIndex level. | ||
|
|
||
| Returns | ||
| ------- | ||
| result : DataFrame of bool | ||
|
There was a problem hiding this comment. We don't need |
||
| Result of the comparison. | ||
|
|
||
| See also | ||
|
There was a problem hiding this comment. I think the There was a problem hiding this comment. I see no current docs page that has |
||
| -------- | ||
| {reverse} | ||
|
There was a problem hiding this comment.
Can you run There was a problem hiding this comment. You are right. And strangely errors did not mention the order of See Also (possibly capitalization of A was the issue?). There was a problem hiding this comment. We still need to add several validations to that script. The order of the sections is one of them. |
||
|
|
||
| Notes | ||
| -------- | ||
| Mismatched indices will be unioned together. | ||
datapythonista marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Examples | ||
| -------- | ||
| {df_examples} | ||
| """ | ||
|
|
||
|
There was a problem hiding this comment. I think we need to explain what's going on here. And I'd probably set The blank line after the docstring is not required. There was a problem hiding this comment. Can you also add this explanation? So users can understand in an easier way what we are showing here. |
||
| _flex_doc_PANEL = """ | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure if I'm missing something, but is this always the same for all methods? It could go directly to the doctring and not in a separate variable if that's the case. Besides good docstrings, it's good if we keep the code as simple as possible. So we usually leave the same
See Alsofor all methods in this case, even if the method being documented is self referencing.Also, do you think we can find something less verbose for the descriptions. Something like
Compare DataFrames for equality elementwisemay be?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Though much of the words are the same, they differ slightly in the middle. Are you advising removing descriptions?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, what I meant is that if it's possible, it'd be good that each of these descriptions is shorter. Just making them more concise if you find the way.