Skip to content

DOC: Fix RT02 issues in docstrings #49968

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
Tracked by #4
mliu08 opened this issue Nov 30, 2022 · 9 comments · Fixed by #50896
Closed
Tracked by #4

DOC: Fix RT02 issues in docstrings #49968

mliu08 opened this issue Nov 30, 2022 · 9 comments · Fixed by #50896
Labels
Docs

Comments

@mliu08
Copy link
Contributor

mliu08 commented Nov 30, 2022 •
edited
Loading

Pandas version checks

  • I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

Several different pandas modules. See below for the list from ./scripts/validate_docstrings.py.

Documentation problem

The functions below have more than just the return type in the first line of the returns section. (RT02: The first line of the Returns section should contain only the type, unless multiple values are being returned)

Suggested fix for documentation

Per the recommendation in #27977, I've created this issue for the RT02 error code. To prevent duplicate work, comment below which functions you're going to take and reference this issue in your PR.

  • pandas.io.formats.style.Styler.apply
  • pandas.io.formats.style.Styler.applymap
  • pandas.io.formats.style.Styler.apply_index
  • pandas.io.formats.style.Styler.applymap_index
  • pandas.io.formats.style.Styler.format
  • pandas.io.formats.style.Styler.format_index
  • pandas.io.formats.style.Styler.relabel_index
  • pandas.io.formats.style.Styler.hide
  • pandas.io.formats.style.Styler.concat
  • pandas.io.formats.style.Styler.set_td_classes
  • pandas.io.formats.style.Styler.set_table_styles
  • pandas.io.formats.style.Styler.set_table_attributes
  • pandas.io.formats.style.Styler.set_tooltips
  • pandas.io.formats.style.Styler.set_caption
  • pandas.io.formats.style.Styler.set_sticky
  • pandas.io.formats.style.Styler.set_properties
  • pandas.io.formats.style.Styler.set_uuid
  • pandas.io.formats.style.Styler.highlight_null
  • pandas.io.formats.style.Styler.highlight_max
  • pandas.io.formats.style.Styler.highlight_min
  • pandas.io.formats.style.Styler.highlight_between
  • pandas.io.formats.style.Styler.highlight_quantile
  • pandas.io.formats.style.Styler.background_gradient
  • pandas.io.formats.style.Styler.text_gradient
  • pandas.io.formats.style.Styler.bar
  • pandas.io.formats.style.Styler.export
  • pandas.io.formats.style.Styler.use
  • pandas.Index.all
  • pandas.Index.any
  • pandas.Index.drop
  • pandas.Index.drop_duplicates
  • pandas.Index.insert
  • pandas.Index.repeat
  • pandas.Index.map
  • pandas.Index.intersection
  • pandas.Index.union
  • pandas.Index.difference
  • pandas.Index.symmetric_difference
  • pandas.Index.get_indexer
  • pandas.Index.get_loc
  • pandas.Index.slice_indexer
  • pandas.Index.slice_locs
  • pandas.CategoricalIndex.rename_categories
  • pandas.CategoricalIndex.reorder_categories
  • pandas.CategoricalIndex.add_categories
  • pandas.CategoricalIndex.remove_categories
  • pandas.CategoricalIndex.remove_unused_categories
  • pandas.IntervalIndex.get_indexer
  • pandas.IntervalIndex.set_closed
  • pandas.MultiIndex.to_frame
  • pandas.MultiIndex.get_loc
  • pandas.MultiIndex.get_loc_level
  • pandas.MultiIndex.get_indexer
  • pandas.MultiIndex.get_level_values
  • pandas.DatetimeIndex.to_pydatetime
  • pandas.TimedeltaIndex.to_pytimedelta
  • pandas.Series.astype
  • pandas.Series.infer_objects
  • pandas.Series.copy
  • pandas.Series.get
  • pandas.Series.pipe
  • pandas.Series.pct_change
  • pandas.Series.align
  • pandas.Series.set_axis
  • pandas.Series.take
  • pandas.Series.first_valid_index
  • pandas.Series.last_valid_index
  • pandas.Series.dt.total_seconds
  • pandas.Series.str.center
  • pandas.Series.str.encode
  • pandas.Series.str.ljust
  • pandas.Series.str.normalize
  • pandas.Series.str.rjust
  • pandas.Series.cat.rename_categories
  • pandas.Series.cat.reorder_categories
  • pandas.Series.cat.add_categories
  • pandas.Series.cat.remove_categories
  • pandas.Series.cat.remove_unused_categories
  • pandas.DataFrame.astype
  • pandas.DataFrame.infer_objects
  • pandas.DataFrame.copy
  • pandas.DataFrame.get
  • pandas.DataFrame.pipe
  • pandas.DataFrame.pct_change
  • pandas.DataFrame.align
  • pandas.DataFrame.set_axis
  • pandas.DataFrame.take
  • pandas.DataFrame.swapaxes
  • pandas.DataFrame.update
  • pandas.DataFrame.first_valid_index
  • pandas.DataFrame.last_valid_index
  • pandas.DataFrame.sparse.to_coo
  • pandas.merge_asof
  • pandas.date_range
  • pandas.arrays.IntervalArray.set_closed
  • pandas.api.types.is_dict_like
  • pandas.api.types.is_file_like
  • pandas.api.types.is_named_tuple
  • pandas.api.types.is_number
  • pandas.api.types.is_re
  • pandas.api.types.is_re_compilable
  • pandas.core.groupby.DataFrameGroupBy.get_group
  • pandas.core.groupby.SeriesGroupBy.get_group
  • pandas.core.groupby.SeriesGroupBy.apply
  • pandas.core.groupby.DataFrameGroupBy.apply
  • pandas.core.groupby.SeriesGroupBy.pipe
  • pandas.core.groupby.DataFrameGroupBy.pipe
  • pandas.core.groupby.DataFrameGroupBy.filter
  • pandas.core.groupby.SeriesGroupBy.filter
  • pandas.core.groupby.DataFrameGroupBy.take
  • pandas.core.groupby.SeriesGroupBy.take
  • pandas.read_pickle
  • pandas.io.json.build_table_schema
  • pandas.read_hdf
  • pandas.core.resample.Resampler.get_group
  • pandas.core.resample.Resampler.transform
  • pandas.core.resample.Resampler.pipe
  • pandas.api.extensions.ExtensionArray.astype
  • pandas.api.extensions.ExtensionArray.dropna
  • pandas.api.extensions.ExtensionArray.isna
  • pandas.api.extensions.ExtensionArray.repeat
  • pandas.api.extensions.ExtensionArray.unique
@mliu08 mliu08 added Docs Needs Triage Issue that has not been reviewed by a pandas team member labels Nov 30, 2022
@mliu08
Copy link
Contributor Author

mliu08 commented Nov 30, 2022

I'll take the pandas.io.formats.style.Styler issues.

mliu08 added a commit to mliu08/pandas that referenced this issue Dec 1, 2022
@mliu08
DOC: fix RT02 errors in pd.io.formats.style pandas-dev#49968
7289437
@mliu08 mliu08 mentioned this issue Dec 1, 2022
Merged
5 tasks
@MarcoGorelli
Copy link
Member

Thanks @mliu08 for doing this! Whilst this is open, it would be good to also add a CI check which only checks the RT02 code, and excludes the files which still need doing. Then, as contributors fix a file, they remove the file from the CI check, until eventually this whole new CI check is removed and RT02 is added to the original one

mroeschke pushed a commit that referenced this issue Dec 5, 2022
@mliu08
DOC: fix RT02 errors in pd.io.formats.style #49968 (#49983)
22d9ffc
@Moisan Moisan removed the Needs Triage Issue that has not been reviewed by a pandas team member label Dec 10, 2022
@luke396 luke396 mentioned this issue Dec 11, 2022
Merged
5 tasks
@luke396
Copy link
Contributor

luke396 commented Dec 12, 2022

These are the remaining:

  • pandas.Index.all
  • pandas.Index.any
  • pandas.IntervalIndex.set_closed
  • pandas.CategoricalIndex.rename_categories
  • pandas.CategoricalIndex.reorder_categories
  • pandas.CategoricalIndex.add_categories
  • pandas.CategoricalIndex.remove_categories
  • pandas.CategoricalIndex.remove_unused_categories
  • pandas.DatetimeIndex.to_pydatetime
  • pandas.TimedeltaIndex.to_pytimedelta
  • pandas.Series.align
  • pandas.Series.dt.total_seconds
  • pandas.Series.cat.rename_categories
  • pandas.Series.cat.reorder_categories
  • pandas.Series.cat.add_categories
  • pandas.Series.cat.remove_categories
  • pandas.Series.cat.remove_unused_categories
  • pandas.DataFrame.align
  • pandas.core.groupby.DataFrameGroupBy.get_group
  • pandas.core.groupby.SeriesGroupBy.get_group
  • pandas.core.groupby.SeriesGroupBy.apply
  • pandas.core.groupby.DataFrameGroupBy.apply
  • pandas.core.groupby.SeriesGroupBy.pipe
  • pandas.core.groupby.DataFrameGroupBy.pipe

@luke396 luke396 mentioned this issue Dec 12, 2022
Merged
5 tasks
@Moisan Moisan mentioned this issue Dec 30, 2022
Merged
5 tasks
@DeaMariaLeon
Copy link
Member

Can I work on these?

pandas.CategoricalIndex.rename_categories
pandas.CategoricalIndex.reorder_categories
pandas.CategoricalIndex.add_categories
pandas.CategoricalIndex.remove_categories
pandas.CategoricalIndex.remove_unused_categories

@MarcoGorelli
Copy link
Member

go ahead, thanks!

@DeaMariaLeon DeaMariaLeon mentioned this issue Jan 10, 2023
Merged
5 tasks
@phofl phofl mentioned this issue Jan 10, 2023
Open
12 tasks
@DeaMariaLeon
Copy link
Member

Can I work on: pandas.Series.dt.total_seconds ?

These functions bellow don't seem to need work on Return, maybe they just need to be removed from code_checks.sh ?
(I think they are all in https://github.com/pandas-dev/pandas/blob/main/pandas/core/arrays/categorical.py if someone wants to correct me).

pandas.Series.cat.rename_categories
pandas.Series.cat.reorder_categories
pandas.Series.cat.add_categories
pandas.Series.cat.remove_categories
pandas.Series.cat.remove_unused_categories

@MarcoGorelli
Copy link
Member

of course, thanks @DeaMariaLeon ! you've been really helpful here, you're welcome to work on as many as you like. and yes, if anything doesn't need work and can already be removed, then please do go ahead and remove it

once these are all done, the final objective (after which we can close this issue) is when we can remove

pandas/ci/code_checks.sh

Line 86 in f47a8b8

MSG='Partially validate docstrings (RT02)' ; echo $MSG

and just include RT02 in

pandas/ci/code_checks.sh

Lines 82 to 84 in f47a8b8

MSG='Validate docstrings (EX04, GL01, GL02, GL03, GL04, GL05, GL06, GL07, GL09, GL10, PR03, PR04, PR05, PR06, PR08, PR09, PR10, RT01, RT04, RT05, SA02, SA03, SA04, SS01, SS02, SS03, SS04, SS05, SS06)' ; echo $MSG
$BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06
RET=$(($RET + $?)) ; echo $MSG "DONE"

@mliu08
Copy link
Contributor Author

mliu08 commented Jan 11, 2023

@MarcoGorelli apologies for the delayed response! I wasn't sure how to add a check that excluded the files that still needed doing, but I see it's been added since.

@DeaMariaLeon DeaMariaLeon mentioned this issue Jan 17, 2023
Merged
5 tasks
@DeaMariaLeon
Copy link
Member

Working on the rest of the functions:

    pandas.Index.all 
    pandas.Index.any 
    pandas.MultiIndex.drop 
    pandas.DatetimeIndex.to_pydatetime 
    pandas.TimedeltaIndex.to_pytimedelta
    pandas.io.formats.style.Styler.export
    pandas.api.extensions.ExtensionArray.astype
    pandas.api.extensions.ExtensionArray.dropna
    pandas.api.extensions.ExtensionArray.isna
    pandas.api.extensions.ExtensionArray.repeat
    pandas.api.extensions.ExtensionArray.unique

@DeaMariaLeon DeaMariaLeon mentioned this issue Jan 20, 2023
Merged
5 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
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

DOC: Fix some RT02 issues in docstrings DeaMariaLeon/pandas
5 participants
@Moisan @DeaMariaLeon @MarcoGorelli @mliu08 @luke396