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')
  """