DOC: Partial fix SA04 errors in docstrings #28792 (feedback needed) (#32823)

Author: dilex42

pandas/core/accessor.py

@@ -211,7 +211,9 @@ def _register_accessor(name, cls):
 
     See Also
     --------
-    {others}
+    register_dataframe_accessor : Register a custom accessor on DataFrame objects.
+    register_series_accessor : Register a custom accessor on Series objects.
+    register_index_accessor : Register a custom accessor on Index objects.
 
     Notes
     -----
@@ -279,33 +281,21 @@ def decorator(accessor):
     return decorator
 
 
-@doc(
-    _register_accessor,
-    klass="DataFrame",
-    others="register_series_accessor, register_index_accessor",
-)
+@doc(_register_accessor, klass="DataFrame")
 def register_dataframe_accessor(name):
     from pandas import DataFrame
 
     return _register_accessor(name, DataFrame)
 
 
-@doc(
-    _register_accessor,
-    klass="Series",
-    others="register_dataframe_accessor, register_index_accessor",
-)
+@doc(_register_accessor, klass="Series")
 def register_series_accessor(name):
     from pandas import Series
 
     return _register_accessor(name, Series)
 
 
-@doc(
-    _register_accessor,
-    klass="Index",
-    others="register_dataframe_accessor, register_series_accessor",
-)
+@doc(_register_accessor, klass="Index")
 def register_index_accessor(name):
     from pandas import Index
 

pandas/core/arrays/categorical.py

@@ -416,12 +416,12 @@ def categories(self):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
         """
         return self.dtype.categories
 
@@ -830,11 +830,11 @@ def set_categories(self, new_categories, ordered=None, rename=False, inplace=Fal
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if ordered is None:
@@ -901,11 +901,11 @@ def rename_categories(self, new_categories, inplace=False):
 
         See Also
         --------
-        reorder_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
 
         Examples
         --------
@@ -969,11 +969,11 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
 
         See Also
         --------
-        rename_categories
-        add_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if set(self.dtype.categories) != set(new_categories):
@@ -1009,11 +1009,11 @@ def add_categories(self, new_categories, inplace=False):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        remove_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if not is_list_like(new_categories):
@@ -1058,11 +1058,11 @@ def remove_categories(self, removals, inplace=False):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_unused_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if not is_list_like(removals):
@@ -1100,11 +1100,11 @@ def remove_unused_categories(self, inplace=False):
 
         See Also
         --------
-        rename_categories
-        reorder_categories
-        add_categories
-        remove_categories
-        set_categories
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        set_categories : Set the categories to the specified ones.
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         cat = self if inplace else self.copy()

pandas/core/dtypes/dtypes.py

@@ -194,7 +194,7 @@ class CategoricalDtype(PandasExtensionDtype, ExtensionDtype):
 
     See Also
     --------
-    Categorical
+    Categorical : Represent a categorical variable in classic R / S-plus fashion.
 
     Notes
     -----

pandas/core/indexes/multi.py

@@ -1584,7 +1584,8 @@ def to_frame(self, index=True, name=None):
 
         See Also
         --------
-        DataFrame
+        DataFrame : Two-dimensional, size-mutable, potentially heterogeneous
+            tabular data.
         """
         from pandas import DataFrame
 

pandas/io/html.py

@@ -1036,7 +1036,7 @@ def read_html(
 
     See Also
     --------
-    read_csv
+    read_csv : Read a comma-separated values (csv) file into DataFrame.
 
     Notes
     -----

pandas/io/sql.py

@@ -313,7 +313,7 @@ def read_sql_query(
     See Also
     --------
     read_sql_table : Read SQL database table into a DataFrame.
-    read_sql
+    read_sql : Read SQL query or database table into a DataFrame.
 
     Notes
     -----

pandas/plotting/_misc.py

@@ -29,10 +29,10 @@ def table(ax, data, rowLabels=None, colLabels=None, **kwargs):
 
 def register():
     """
-    Register Pandas Formatters and Converters with matplotlib.
+    Register pandas formatters and converters with matplotlib.
 
     This function modifies the global ``matplotlib.units.registry``
-    dictionary. Pandas adds custom converters for
+    dictionary. pandas adds custom converters for
 
     * pd.Timestamp
     * pd.Period
@@ -43,15 +43,15 @@ def register():
 
     See Also
     --------
-    deregister_matplotlib_converters
+    deregister_matplotlib_converters : Remove pandas formatters and converters.
     """
     plot_backend = _get_plot_backend("matplotlib")
     plot_backend.register()
 
 
 def deregister():
     """
-    Remove pandas' formatters and converters.
+    Remove pandas formatters and converters.
 
     Removes the custom converters added by :func:`register`. This
     attempts to set the state of the registry back to the state before
@@ -62,7 +62,8 @@ def deregister():
 
     See Also
     --------
-    register_matplotlib_converters
+    register_matplotlib_converters : Register pandas formatters and converters
+        with matplotlib.
     """
     plot_backend = _get_plot_backend("matplotlib")
     plot_backend.deregister()
@@ -155,7 +156,7 @@ def radviz(frame, class_column, ax=None, color=None, colormap=None, **kwds):
     Parameters
     ----------
     frame : `DataFrame`
-        Pandas object holding the data.
+        pandas object holding the data.
     class_column : str
         Column name containing the name of the data point category.
     ax : :class:`matplotlib.axes.Axes`, optional
@@ -270,7 +271,7 @@ def bootstrap_plot(series, fig=None, size=50, samples=500, **kwds):
     Parameters
     ----------
     series : pandas.Series
-        Pandas Series from where to get the samplings for the bootstrapping.
+        pandas Series from where to get the samplings for the bootstrapping.
     fig : matplotlib.figure.Figure, default None
         If given, it will use the `fig` reference for plotting instead of
         creating a new one with default parameters.

pandas/tseries/frequencies.py

@@ -91,7 +91,7 @@ def to_offset(freq) -> Optional[DateOffset]:
 
     See Also
     --------
-    DateOffset
+    DateOffset : Standard kind of date increment used for a date range.
 
     Examples
     --------