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

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
     -----
@@ -280,9 +282,7 @@ def decorator(accessor):
 
 
 @doc(
-    _register_accessor,
-    klass="DataFrame",
-    others="register_series_accessor, register_index_accessor",
+    _register_accessor, klass="DataFrame",
 )
 def register_dataframe_accessor(name):
     from pandas import DataFrame
@@ -291,9 +291,7 @@ def register_dataframe_accessor(name):
 
 
 @doc(
-    _register_accessor,
-    klass="Series",
-    others="register_dataframe_accessor, register_index_accessor",
+    _register_accessor, klass="Series",
 )
 def register_series_accessor(name):
     from pandas import Series
@@ -302,9 +300,7 @@ def register_series_accessor(name):
 
 
 @doc(
-    _register_accessor,
-    klass="Index",
-    others="register_dataframe_accessor, register_series_accessor",
+    _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 categories.
         """
         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 categories.
 
         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 categories.
         """
         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 categories.
         """
         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 categories.
         """
         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 categories.
         """
         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,7 +29,7 @@ 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
@@ -43,7 +43,7 @@ def register():
 
     See Also
     --------
-    deregister_matplotlib_converters
+    deregister_matplotlib_converters : Remove pandas’ formatters and converters.
     """
     plot_backend = _get_plot_backend("matplotlib")
     plot_backend.register()
@@ -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()

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