DOC: Fixes to docstrings formatting (#28096)

Author: realjohnward

pandas/core/generic.py

@@ -1875,7 +1875,7 @@ def __iter__(self):
     # can we get a better explanation of this?
     def keys(self):
         """
-        Get the 'info axis' (see Indexing for more)
+        Get the 'info axis' (see Indexing for more).
 
         This is index for Series, columns for DataFrame.
 

pandas/io/clipboards.py

@@ -9,18 +9,21 @@
 
 def read_clipboard(sep=r"\s+", **kwargs):  # pragma: no cover
     r"""
-    Read text from clipboard and pass to read_csv. See read_csv for the
-    full argument list
+    Read text from clipboard and pass to read_csv.
 
     Parameters
     ----------
     sep : str, default '\s+'
         A string or regex delimiter. The default of '\s+' denotes
         one or more whitespace characters.
 
+    **kwargs
+        See read_csv for the full argument list.
+
     Returns
     -------
-    parsed : DataFrame
+    DataFrame
+        A parsed DataFrame object.
     """
     encoding = kwargs.pop("encoding", "utf-8")
 

pandas/io/excel/_base.py

@@ -837,10 +837,10 @@ def parse(
         **kwds
     ):
         """
-        Parse specified sheet(s) into a DataFrame
+        Parse specified sheet(s) into a DataFrame.
 
         Equivalent to read_excel(ExcelFile, ...)  See the read_excel
-        docstring for more info on accepted parameters
+        docstring for more info on accepted parameters.
 
         Returns
         -------

pandas/io/pytables.py

@@ -431,8 +431,9 @@ def _is_metadata_of(group, parent_group):
 class HDFStore:
 
     """
-    Dict-like IO interface for storing pandas objects in PyTables
-    either Fixed or Table format.
+    Dict-like IO interface for storing pandas objects in PyTables.
+
+    Either Fixed or Table format.
 
     Parameters
     ----------
@@ -564,13 +565,12 @@ def __exit__(self, exc_type, exc_value, traceback):
 
     def keys(self):
         """
-        Return a (potentially unordered) list of the keys corresponding to the
-        objects stored in the HDFStore. These are ABSOLUTE path-names (e.g.
-        have the leading '/'
+        Return a list of keys corresponding to objects stored in HDFStore.
 
         Returns
         -------
         list
+            List of ABSOLUTE path-names (e.g. have the leading '/').
         """
         return [n._v_pathname for n in self.groups()]
 
@@ -703,15 +703,16 @@ def flush(self, fsync=False):
 
     def get(self, key):
         """
-        Retrieve pandas object stored in file
+        Retrieve pandas object stored in file.
 
         Parameters
         ----------
         key : object
 
         Returns
         -------
-        obj : same type as object stored in file
+        object
+            Same type as object stored in file.
         """
         group = self.get_node(key)
         if group is None:
@@ -731,25 +732,31 @@ def select(
         **kwargs
     ):
         """
-        Retrieve pandas object stored in file, optionally based on where
-        criteria
+        Retrieve pandas object stored in file, optionally based on where criteria.
 
         Parameters
         ----------
         key : object
-        where : list of Term (or convertible) objects, optional
-        start : integer (defaults to None), row number to start selection
-        stop  : integer (defaults to None), row number to stop selection
-        columns : a list of columns that if not None, will limit the return
-            columns
-        iterator : boolean, return an iterator, default False
-        chunksize : nrows to include in iteration, return an iterator
-        auto_close : boolean, should automatically close the store when
-            finished, default is False
+                Object being retrieved from file.
+        where : list, default None
+                List of Term (or convertible) objects, optional.
+        start : int, default None
+                Row number to start selection.
+        stop : int, default None
+                Row number to stop selection.
+        columns : list, default None
+                A list of columns that if not None, will limit the return columns.
+        iterator : bool, default False
+                Returns an iterator.
+        chunksize : int, default None
+                Number or rows to include in iteration, return an iterator.
+        auto_close : bool, default False
+            Should automatically close the store when finished.
 
         Returns
         -------
-        The selected object
+        object
+            Retrieved object from file.
         """
         group = self.get_node(key)
         if group is None:
@@ -929,28 +936,30 @@ def func(_start, _stop, _where):
 
     def put(self, key, value, format=None, append=False, **kwargs):
         """
-        Store object in HDFStore
+        Store object in HDFStore.
 
         Parameters
         ----------
-        key      : object
-        value    : {Series, DataFrame}
-        format   : 'fixed(f)|table(t)', default is 'fixed'
+        key : object
+        value : {Series, DataFrame}
+        format : 'fixed(f)|table(t)', default is 'fixed'
             fixed(f) : Fixed format
-                       Fast writing/reading. Not-appendable, nor searchable
+                       Fast writing/reading. Not-appendable, nor searchable.
             table(t) : Table format
                        Write as a PyTables Table structure which may perform
                        worse but allow more flexible operations like searching
-                       / selecting subsets of the data
-        append   : boolean, default False
+                       / selecting subsets of the data.
+        append   : bool, default False
             This will force Table format, append the input data to the
             existing.
-        data_columns : list of columns to create as data columns, or True to
+        data_columns : list, default None
+            List of columns to create as data columns, or True to
             use all columns. See `here
             <http://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#query-via-data-columns>`__.
-        encoding : default None, provide an encoding for strings
-        dropna   : boolean, default False, do not write an ALL nan row to
-            the store settable by the option 'io.hdf.dropna_table'
+        encoding : str, default None
+            Provide an encoding for strings.
+        dropna   : bool, default False, do not write an ALL nan row to
+            The store settable by the option 'io.hdf.dropna_table'.
         """
         if format is None:
             format = get_option("io.hdf.default_format") or "fixed"
@@ -1165,12 +1174,15 @@ def create_table_index(self, key, **kwargs):
         s.create_index(**kwargs)
 
     def groups(self):
-        """return a list of all the top-level nodes (that are not themselves a
-        pandas storage object)
+        """
+        Return a list of all the top-level nodes.
+
+        Each node returned is not a pandas storage object.
 
         Returns
         -------
         list
+            List of objects.
         """
         _tables()
         self._check_if_open()
@@ -1188,10 +1200,12 @@ def groups(self):
         ]
 
     def walk(self, where="/"):
-        """ Walk the pytables group hierarchy for pandas objects
+        """
+        Walk the pytables group hierarchy for pandas objects.
 
         This generator will yield the group path, subgroups and pandas object
         names for each group.
+
         Any non-pandas PyTables objects that are not a group will be ignored.
 
         The `where` group itself is listed first (preorder), then each of its
@@ -1202,18 +1216,17 @@ def walk(self, where="/"):
 
         Parameters
         ----------
-        where : str, optional
+        where : str, default "/"
             Group where to start walking.
-            If not supplied, the root group is used.
 
         Yields
         ------
         path : str
-            Full path to a group (without trailing '/')
-        groups : list of str
-            names of the groups contained in `path`
-        leaves : list of str
-            names of the pandas objects contained in `path`
+            Full path to a group (without trailing '/').
+        groups : list
+            Names (strings) of the groups contained in `path`.
+        leaves : list
+            Names (strings) of the pandas objects contained in `path`.
         """
         _tables()
         self._check_if_open()

pandas/tseries/offsets.py

@@ -204,8 +204,7 @@ def __add__(date):
     normalize : bool, default False
         Whether to round the result of a DateOffset addition down to the
         previous midnight.
-    **kwds
-        Temporal parameter that add to or replace the offset value.
+    **kwds : Temporal parameter that add to or replace the offset value.
 
         Parameters that **add** to the offset (like Timedelta):
 
@@ -233,16 +232,19 @@ def __add__(date):
 
     See Also
     --------
-    dateutil.relativedelta.relativedelta
+    dateutil.relativedelta.relativedelta : The relativedelta type is designed
+        to be applied to an existing datetime an can replace specific components of
+        that datetime, or represents an interval of time.
 
     Examples
     --------
+    >>> from pandas.tseries.offsets import DateOffset
     >>> ts = pd.Timestamp('2017-01-01 09:10:11')
     >>> ts + DateOffset(months=3)
     Timestamp('2017-04-01 09:10:11')
 
     >>> ts = pd.Timestamp('2017-01-01 09:10:11')
-    >>> ts + DateOffset(month=3)
+    >>> ts + DateOffset(months=2)
     Timestamp('2017-03-01 09:10:11')
     """