DOC: Fix format of the See Also descriptions (pandas-dev#23654)

* pandas refs 23630, partial.

pandas/core/arrays/categorical.py

@@ -315,8 +315,8 @@ class Categorical(ExtensionArray, PandasObject):
 
     See Also
     --------
-    pandas.api.types.CategoricalDtype : Type for categorical data
-    CategoricalIndex : An Index with an underlying ``Categorical``
+    pandas.api.types.CategoricalDtype : Type for categorical data.
+    CategoricalIndex : An Index with an underlying ``Categorical``.
     """
 
     # For comparisons, so that numpy uses our implementation if the compare
@@ -1366,9 +1366,9 @@ def isna(self):
 
         See Also
         --------
-        isna : top-level isna
-        isnull : alias of isna
-        Categorical.notna : boolean inverse of Categorical.isna
+        isna : Top-level isna.
+        isnull : Alias of isna.
+        Categorical.notna : Boolean inverse of Categorical.isna.
 
         """
 
@@ -1389,9 +1389,9 @@ def notna(self):
 
         See Also
         --------
-        notna : top-level notna
-        notnull : alias of notna
-        Categorical.isna : boolean inverse of Categorical.notna
+        notna : Top-level notna.
+        notnull : Alias of notna.
+        Categorical.isna : Boolean inverse of Categorical.notna.
 
         """
         return ~self.isna()
@@ -2371,7 +2371,7 @@ def isin(self, values):
 
         See Also
         --------
-        pandas.Series.isin : equivalent method on Series
+        pandas.Series.isin : Equivalent method on Series.
 
         Examples
         --------

pandas/core/arrays/datetimes.py

@@ -584,7 +584,7 @@ def tz_convert(self, tz):
 
         See Also
         --------
-        DatetimeIndex.tz : A timezone that has a variable offset from UTC
+        DatetimeIndex.tz : A timezone that has a variable offset from UTC.
         DatetimeIndex.tz_localize : Localize tz-naive DatetimeIndex to a
             given time zone, or remove timezone from a tz-aware DatetimeIndex.
 
@@ -894,8 +894,8 @@ def to_period(self, freq=None):
 
         See Also
         --------
-        pandas.PeriodIndex: Immutable ndarray holding ordinal values
-        pandas.DatetimeIndex.to_pydatetime: Return DatetimeIndex as object
+        pandas.PeriodIndex: Immutable ndarray holding ordinal values.
+        pandas.DatetimeIndex.to_pydatetime: Return DatetimeIndex as object.
         """
         from pandas.core.arrays import PeriodArray
 

pandas/core/arrays/interval.py

@@ -94,11 +94,11 @@
 
 See Also
 --------
-Index : The base pandas Index type
-Interval : A bounded slice-like interval; the elements of an %(klass)s
-interval_range : Function to create a fixed frequency IntervalIndex
-cut : Bin values into discrete Intervals
-qcut : Bin values into equal-sized Intervals based on rank or sample quantiles
+Index : The base pandas Index type.
+Interval : A bounded slice-like interval; the elements of an %(klass)s.
+interval_range : Function to create a fixed frequency IntervalIndex.
+cut : Bin values into discrete Intervals.
+qcut : Bin values into equal-sized Intervals based on rank or sample quantiles.
 """
 
 
@@ -244,9 +244,9 @@ def _from_factorized(cls, values, original):
 
     See Also
     --------
-    interval_range : Function to create a fixed frequency IntervalIndex
-    %(klass)s.from_arrays : Construct from a left and right array
-    %(klass)s.from_tuples : Construct from a sequence of tuples
+    interval_range : Function to create a fixed frequency IntervalIndex.
+    %(klass)s.from_arrays : Construct from a left and right array.
+    %(klass)s.from_tuples : Construct from a sequence of tuples.
     """
 
     @classmethod
@@ -354,13 +354,13 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None):
 
     See Also
     --------
-    interval_range : Function to create a fixed frequency IntervalIndex
+    interval_range : Function to create a fixed frequency IntervalIndex.
     %(klass)s.from_arrays : Construct an %(klass)s from a left and
-                                right array
+                                right array.
     %(klass)s.from_breaks : Construct an %(klass)s from an array of
-                                splits
+                                splits.
     %(klass)s.from_tuples : Construct an %(klass)s from an
-                                array-like of tuples
+                                array-like of tuples.
     """
 
     _interval_shared_docs['from_tuples'] = """
@@ -389,11 +389,11 @@ def from_arrays(cls, left, right, closed='right', copy=False, dtype=None):
 
     See Also
     --------
-    interval_range : Function to create a fixed frequency IntervalIndex
+    interval_range : Function to create a fixed frequency IntervalIndex.
     %(klass)s.from_arrays : Construct an %(klass)s from a left and
-                                right array
+                                right array.
     %(klass)s.from_breaks : Construct an %(klass)s from an array of
-                                splits
+                                splits.
     """
 
     @classmethod
@@ -1027,9 +1027,9 @@ def repeat(self, repeats, **kwargs):
 
         See Also
         --------
-        Index.repeat : Equivalent function for Index
-        Series.repeat : Equivalent function for Series
-        numpy.repeat : Underlying implementation
+        Index.repeat : Equivalent function for Index.
+        Series.repeat : Equivalent function for Series.
+        numpy.repeat : Underlying implementation.
         """
         left_repeat = self.left.repeat(repeats, **kwargs)
         right_repeat = self.right.repeat(repeats, **kwargs)

pandas/core/arrays/period.py

@@ -146,8 +146,8 @@ class PeriodArray(dtl.DatetimeLikeArrayMixin, ExtensionArray):
 
     See Also
     --------
-    period_array : Create a new PeriodArray
-    pandas.PeriodIndex : Immutable Index for period data
+    period_array : Create a new PeriodArray.
+    pandas.PeriodIndex : Immutable Index for period data.
     """
     # array priority higher than numpy scalars
     __array_priority__ = 1000

pandas/core/base.py

@@ -1014,8 +1014,8 @@ def value_counts(self, normalize=False, sort=True, ascending=False,
 
         See Also
         --------
-        Series.count: number of non-NA elements in a Series
-        DataFrame.count: number of non-NA elements in a DataFrame
+        Series.count: Number of non-NA elements in a Series.
+        DataFrame.count: Number of non-NA elements in a DataFrame.
 
         Examples
         --------

pandas/core/dtypes/inference.py

@@ -44,7 +44,7 @@ def is_number(obj):
 
     See Also
     --------
-    pandas.api.types.is_integer: checks a subgroup of numbers
+    pandas.api.types.is_integer: Checks a subgroup of numbers.
 
     Examples
     --------

pandas/core/dtypes/missing.py

@@ -43,7 +43,7 @@ def isna(obj):
 
     See Also
     --------
-    notna : boolean inverse of pandas.isna.
+    notna : Boolean inverse of pandas.isna.
     Series.isna : Detect missing values in a Series.
     DataFrame.isna : Detect missing values in a DataFrame.
     Index.isna : Detect missing values in an Index.
@@ -274,7 +274,7 @@ def notna(obj):
 
     See Also
     --------
-    isna : boolean inverse of pandas.notna.
+    isna : Boolean inverse of pandas.notna.
     Series.notna : Detect valid values in a Series.
     DataFrame.notna : Detect valid values in a DataFrame.
     Index.notna : Detect valid values in an Index.

pandas/core/frame.py

@@ -221,9 +221,9 @@
 
 See Also
 --------
-merge_ordered : merge with optional filling/interpolation.
-merge_asof : merge on nearest keys.
-DataFrame.join : similar method using indices.
+merge_ordered : Merge with optional filling/interpolation.
+merge_asof : Merge on nearest keys.
+DataFrame.join : Similar method using indices.
 
 Examples
 --------
@@ -348,10 +348,10 @@ class DataFrame(NDFrame):
 
     See Also
     --------
-    DataFrame.from_records : constructor from tuples, also record arrays
-    DataFrame.from_dict : from dicts of Series, arrays, or dicts
-    DataFrame.from_items : from sequence of (key, value) pairs
-    pandas.read_csv, pandas.read_table, pandas.read_clipboard
+    DataFrame.from_records : Constructor from tuples, also record arrays.
+    DataFrame.from_dict : From dicts of Series, arrays, or dicts.
+    DataFrame.from_items : From sequence of (key, value) pairs
+        pandas.read_csv, pandas.read_table, pandas.read_clipboard.
     """
 
     @property
@@ -1066,8 +1066,8 @@ def from_dict(cls, data, orient='columns', dtype=None, columns=None):
         See Also
         --------
         DataFrame.from_records : DataFrame from ndarray (structured
-            dtype), list of tuples, dict, or DataFrame
-        DataFrame : DataFrame object creation using constructor
+            dtype), list of tuples, dict, or DataFrame.
+        DataFrame : DataFrame object creation using constructor.
 
         Examples
         --------
@@ -1484,9 +1484,9 @@ def to_records(self, index=True, convert_datetime64=None):
 
         See Also
         --------
-        DataFrame.from_records: convert structured or record ndarray
+        DataFrame.from_records: Convert structured or record ndarray
             to DataFrame.
-        numpy.recarray: ndarray that allows field access using
+        numpy.recarray: An ndarray that allows field access using
             attributes, analogous to typed columns in a
             spreadsheet.
 
@@ -1900,9 +1900,10 @@ def to_stata(self, fname, convert_dates=None, write_index=True,
 
         See Also
         --------
-        pandas.read_stata : Import Stata data files
-        pandas.io.stata.StataWriter : low-level writer for Stata data files
-        pandas.io.stata.StataWriter117 : low-level writer for version 117 files
+        pandas.read_stata : Import Stata data files.
+        pandas.io.stata.StataWriter : Low-level writer for Stata data files.
+        pandas.io.stata.StataWriter117 : Low-level writer for version 117
+            files.
 
         Examples
         --------
@@ -3729,9 +3730,9 @@ def drop(self, labels=None, axis=0, index=None, columns=None,
         --------
         DataFrame.loc : Label-location based indexer for selection by label.
         DataFrame.dropna : Return DataFrame with labels on given axis omitted
-            where (all or any) data are missing
+            where (all or any) data are missing.
         DataFrame.drop_duplicates : Return DataFrame with duplicate rows
-            removed, optionally only considering certain columns
+            removed, optionally only considering certain columns.
         Series.drop : Return Series with specified index labels removed.
 
         Raises
@@ -4683,7 +4684,7 @@ def nlargest(self, n, columns, keep='first'):
         --------
         DataFrame.nsmallest : Return the first `n` rows ordered by `columns` in
             ascending order.
-        DataFrame.sort_values : Sort DataFrame by the values
+        DataFrame.sort_values : Sort DataFrame by the values.
         DataFrame.head : Return the first `n` rows without re-ordering.
 
         Notes
@@ -5070,7 +5071,7 @@ def combine(self, other, func, fill_value=None, overwrite=True):
         See Also
         --------
         DataFrame.combine_first : Combine two DataFrame objects and default to
-            non-null values in frame calling the method
+            non-null values in frame calling the method.
         """
         other_idxlen = len(other.index)  # save for compare
 
@@ -5176,7 +5177,7 @@ def combine_first(self, other):
         See Also
         --------
         DataFrame.combine : Perform series-wise operation on two DataFrames
-            using a given function
+            using a given function.
         """
         import pandas.core.computation.expressions as expressions
 
@@ -5388,9 +5389,9 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
 
         See Also
         --------
-        DataFrame.pivot_table : generalization of pivot that can handle
+        DataFrame.pivot_table : Generalization of pivot that can handle
             duplicate values for one index/column pair.
-        DataFrame.unstack : pivot based on the index values instead of a
+        DataFrame.unstack : Pivot based on the index values instead of a
             column.
 
         Notes
@@ -5576,8 +5577,8 @@ def pivot(self, index=None, columns=None, values=None):
 
         See Also
         --------
-        DataFrame.pivot : pivot without aggregation that can handle
-            non-numeric data
+        DataFrame.pivot : Pivot without aggregation that can handle
+            non-numeric data.
         """
 
     @Substitution('')
@@ -6226,9 +6227,9 @@ def apply(self, func, axis=0, broadcast=None, raw=False, reduce=None,
 
         See Also
         --------
-        DataFrame.applymap: For elementwise operations
-        DataFrame.aggregate: only perform aggregating type operations
-        DataFrame.transform: only perform transforming type operations
+        DataFrame.applymap: For elementwise operations.
+        DataFrame.aggregate: Only perform aggregating type operations.
+        DataFrame.transform: Only perform transforming type operations.
 
         Examples
         --------
@@ -6335,7 +6336,7 @@ def applymap(self, func):
 
         See Also
         --------
-        DataFrame.apply : Apply a function along input axis of DataFrame
+        DataFrame.apply : Apply a function along input axis of DataFrame.
 
         Examples
         --------
@@ -6419,7 +6420,7 @@ def append(self, other, ignore_index=False,
         See Also
         --------
         pandas.concat : General function to concatenate DataFrame, Series
-            or Panel objects
+            or Panel objects.
 
         Examples
         --------
@@ -6886,10 +6887,10 @@ def cov(self, min_periods=None):
 
         See Also
         --------
-        pandas.Series.cov : compute covariance with another Series
-        pandas.core.window.EWM.cov: exponential weighted sample covariance
-        pandas.core.window.Expanding.cov : expanding sample covariance
-        pandas.core.window.Rolling.cov : rolling sample covariance
+        pandas.Series.cov : Compute covariance with another Series.
+        pandas.core.window.EWM.cov: Exponential weighted sample covariance.
+        pandas.core.window.Expanding.cov : Expanding sample covariance.
+        pandas.core.window.Rolling.cov : Rolling sample covariance.
 
         Notes
         -----
@@ -7046,11 +7047,11 @@ def count(self, axis=0, level=None, numeric_only=False):
 
         See Also
         --------
-        Series.count: number of non-NA elements in a Series
-        DataFrame.shape: number of DataFrame rows and columns (including NA
-            elements)
-        DataFrame.isna: boolean same-sized DataFrame showing places of NA
-            elements
+        Series.count: Number of non-NA elements in a Series.
+        DataFrame.shape: Number of DataFrame rows and columns (including NA
+            elements).
+        DataFrame.isna: Boolean same-sized DataFrame showing places of NA
+            elements.
 
         Examples
         --------