Pandas DOC: Fix RT02 issues in docstrings

Pandas version checks

[X] 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.

[x] pandas.io.formats.style.Styler.apply
[x] pandas.io.formats.style.Styler.applymap
[x] pandas.io.formats.style.Styler.apply_index
[x] 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
[x] pandas.io.formats.style.Styler.hide
[x] pandas.io.formats.style.Styler.concat
[x] pandas.io.formats.style.Styler.set_td_classes
[x] pandas.io.formats.style.Styler.set_table_styles
[x] pandas.io.formats.style.Styler.set_table_attributes
[x] pandas.io.formats.style.Styler.set_tooltips
[x] pandas.io.formats.style.Styler.set_caption
[x] pandas.io.formats.style.Styler.set_sticky
[x] pandas.io.formats.style.Styler.set_properties
[x] pandas.io.formats.style.Styler.set_uuid
[x] pandas.io.formats.style.Styler.highlight_null
[x] pandas.io.formats.style.Styler.highlight_max
[x] pandas.io.formats.style.Styler.highlight_min
[x] pandas.io.formats.style.Styler.highlight_between
[x] pandas.io.formats.style.Styler.highlight_quantile
[x] pandas.io.formats.style.Styler.background_gradient
[x] pandas.io.formats.style.Styler.text_gradient
[x] pandas.io.formats.style.Styler.bar
[x] pandas.io.formats.style.Styler.export
[x] pandas.io.formats.style.Styler.use
[ ] pandas.Index.all
[ ] pandas.Index.any
[x] pandas.Index.drop
[x] pandas.Index.drop_duplicates
[x] pandas.Index.insert
[x] pandas.Index.repeat
[x] pandas.Index.map
[x] pandas.Index.intersection
[x] pandas.Index.union
[x] pandas.Index.difference
[x] pandas.Index.symmetric_difference
[x] pandas.Index.get_indexer
[x] pandas.Index.get_loc
[x] pandas.Index.slice_indexer
[x] 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
[x] pandas.IntervalIndex.get_indexer
[ ] pandas.IntervalIndex.set_closed
[x] pandas.MultiIndex.to_frame
[x] pandas.MultiIndex.get_loc
[x] pandas.MultiIndex.get_loc_level
[x] pandas.MultiIndex.get_indexer
[x] pandas.MultiIndex.get_level_values
[ ] pandas.DatetimeIndex.to_pydatetime
[ ] pandas.TimedeltaIndex.to_pytimedelta
[x] pandas.Series.astype
[x] pandas.Series.infer_objects
[x] pandas.Series.copy
[x] pandas.Series.get
[x] pandas.Series.pipe
[x] pandas.Series.pct_change
[ ] pandas.Series.align
[x] pandas.Series.set_axis
[x] pandas.Series.take
[x] pandas.Series.first_valid_index
[x] pandas.Series.last_valid_index
[ ] pandas.Series.dt.total_seconds
[x] pandas.Series.str.center
[x] pandas.Series.str.encode
[x] pandas.Series.str.ljust
[x] pandas.Series.str.normalize
[x] 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
[x] pandas.DataFrame.astype
[x] pandas.DataFrame.infer_objects
[x] pandas.DataFrame.copy
[x] pandas.DataFrame.get
[x] pandas.DataFrame.pipe
[x] pandas.DataFrame.pct_change
[ ] pandas.DataFrame.align
[x] pandas.DataFrame.set_axis
[x] pandas.DataFrame.take
[x] pandas.DataFrame.swapaxes
[x] pandas.DataFrame.update
[x] pandas.DataFrame.first_valid_index
[x] pandas.DataFrame.last_valid_index
[x] pandas.DataFrame.sparse.to_coo
[x] pandas.merge_asof
[x] pandas.date_range
[x] pandas.arrays.IntervalArray.set_closed
[x] pandas.api.types.is_dict_like
[x] pandas.api.types.is_file_like
[x] pandas.api.types.is_named_tuple
[x] pandas.api.types.is_number
[x] pandas.api.types.is_re
[x] 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
[x] pandas.core.groupby.DataFrameGroupBy.filter
[x] pandas.core.groupby.SeriesGroupBy.filter
[x] pandas.core.groupby.DataFrameGroupBy.take
[x] pandas.core.groupby.SeriesGroupBy.take
[x] pandas.read_pickle
[x] pandas.io.json.build_table_schema
[x] pandas.read_hdf
[x] pandas.core.resample.Resampler.get_group
[x] pandas.core.resample.Resampler.transform
[x] pandas.core.resample.Resampler.pipe
[x] pandas.api.extensions.ExtensionArray.astype
[x] pandas.api.extensions.ExtensionArray.dropna
[x] pandas.api.extensions.ExtensionArray.isna
[x] pandas.api.extensions.ExtensionArray.repeat
[x] pandas.api.extensions.ExtensionArray.unique

Comment From: mliu08

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

Comment From: MarcoGorelli

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

Comment From: luke396

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

Comment From: DeaMariaLeon

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

Comment From: MarcoGorelli

go ahead, thanks!

Comment From: DeaMariaLeon

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

Comment From: MarcoGorelli

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

https://github.com/pandas-dev/pandas/blob/f47a8b83ec10c906429bde6d198f563a869ed7ee/ci/code_checks.sh#L86

and just include RT02 in

https://github.com/pandas-dev/pandas/blob/f47a8b83ec10c906429bde6d198f563a869ed7ee/ci/code_checks.sh#L82-L84

Comment From: mliu08

@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.

Comment From: DeaMariaLeon

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