DOC/BLD: fix annoying sphinx bugs

cpcloud · cpcloud · commit fbb9601efccb · 2013-05-30T19:12:58.000-04:00
diff --git a/pandas/core/common.py b/pandas/core/common.py
@@ -1348,8 +1348,8 @@ def iterpairs(seq):
     -------
     iterator returning overlapping pairs of elements
 
-    Example
-    -------
+    Examples
+    --------
     >>> iterpairs([1, 2, 3, 4])
     [(1, 2), (2, 3), (3, 4)
     """
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -1374,9 +1374,8 @@ def to_csv(self, path_or_buf, sep=",", na_rep='', float_format=None,
                mode='w', nanRep=None, encoding=None, quoting=None,
                line_terminator='\n', chunksize=None,
                tupleize_cols=True, **kwds):
-        """
-        Write DataFrame to a comma-separated values (csv) file
-        
+        r"""Write DataFrame to a comma-separated values (csv) file
+
         Parameters
         ----------
         path_or_buf : string or file handle / StringIO
@@ -1390,8 +1389,8 @@ def to_csv(self, path_or_buf, sep=",", na_rep='', float_format=None,
         cols : sequence, optional
             Columns to write
         header : boolean or list of string, default True
-            Write out column names. If a list of string is given it is
-            assumed to be aliases for the column names
+            Write out column names. If a list of string is given it is assumed
+            to be aliases for the column names
         index : boolean, default True
             Write row names (index)
         index_label : string or sequence, or False, default None
@@ -1400,21 +1399,23 @@ def to_csv(self, path_or_buf, sep=",", na_rep='', float_format=None,
             sequence should be given if the DataFrame uses MultiIndex.  If
             False do not print fields for index names. Use index_label=False
             for easier importing in R
-        nanRep : deprecated, use na_rep
-        mode : Python write mode, default 'w'
+        nanRep : None
+            deprecated, use na_rep
+        mode : str
+            Python write mode, default 'w'
         encoding : string, optional
             a string representing the encoding to use if the contents are
             non-ascii, for python versions prior to 3
-        line_terminator: string, default '\n'
+        line_terminator : string, default '\\n'
             The newline character or character sequence to use in the output
             file
         quoting : optional constant from csv module
             defaults to csv.QUOTE_MINIMAL
-        chunksize : rows to write at a time
+        chunksize : int or None
+            rows to write at a time
         tupleize_cols : boolean, default True
             write multi_index columns as a list of tuples (if True)
             or new (expanded format) if False)
-
         """
         if nanRep is not None:  # pragma: no cover
             import warnings
@@ -2401,27 +2402,31 @@ def xs(self, key, axis=0, level=None, copy=True):
     _xs = xs
 
     def lookup(self, row_labels, col_labels):
-        """
-        Label-based "fancy indexing" function for DataFrame. Given equal-length
-        arrays of row and column labels, return an array of the values
-        corresponding to each (row, col)  pair.
+        """Label-based "fancy indexing" function for DataFrame. Given
+        equal-length arrays of row and column labels, return an array of the
+        values corresponding to each (row, col)  pair.
 
         Parameters
         ----------
         row_labels : sequence
+            The row labels to use for lookup
         col_labels : sequence
+            The column labels to use for lookup
 
         Notes
         -----
         Akin to
 
-        result = []
-        for row, col in zip(row_labels, col_labels):
-            result.append(df.get_value(row, col))
+            .. code-block:: python
 
-        Example
-        -------
+                result = []
+                for row, col in zip(row_labels, col_labels):
+                    result.append(df.get_value(row, col))
+
+        Examples
+        --------
         values : ndarray
+            The found values
 
         """
         from itertools import izip
@@ -3483,20 +3488,26 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
         Parameters
         ----------
         to_replace : str, regex, list, dict, Series, numeric, or None
+
             * str or regex:
+
                 - str: string exactly matching `to_replace` will be replaced
                   with `value`
                 - regex: regexs matching `to_replace` will be replaced with
                   `value`
+
             * list of str, regex, or numeric:
+
                 - First, if `to_replace` and `value` are both lists, they
                   **must** be the same length.
                 - Second, if ``regex=True`` then all of the strings in **both**
                   lists will be interpreted as regexs otherwise they will match
                   directly. This doesn't matter much for `value` since there
                   are only a few possible substitution regexes you can use.
                 - str and regex rules apply as above.
+
             * dict:
+
                 - Nested dictionaries, e.g., {'a': {'b': nan}}, are read as
                   follows: look in column 'a' for the value 'b' and replace it
                   with nan. You can nest regular expressions as well. Note that
@@ -3505,11 +3516,14 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
                 - Keys map to column names and values map to substitution
                   values. You can treat this as a special case of passing two
                   lists except that you are specifying the column to search in.
+
             * None:
+
                 - This means that the ``regex`` argument must be a string,
                   compiled regular expression, or list, dict, ndarray or Series
                   of such elements. If `value` is also ``None`` then this
                   **must** be a nested dictionary or ``Series``.
+
             See the examples section for examples of each of these.
         value : scalar, dict, list, str, regex, default None
             Value to use to fill holes (e.g. 0), alternately a dict of values
diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py
@@ -1374,8 +1374,8 @@ def aggregate(self, func_or_funcs, *args, **kwargs):
         -----
         agg is an alias for aggregate. Use it.
 
-        Example
-        -------
+        Examples
+        --------
         >>> series
         bar    1.0
         baz    2.0
@@ -1523,8 +1523,8 @@ def transform(self, func, *args, **kwargs):
         func : function
             To apply to each group. Should return a Series with the same index
 
-        Example
-        -------
+        Examples
+        --------
         >>> grouped.transform(lambda x: (x - x.mean()) / x.std())
 
         Returns
@@ -1906,7 +1906,7 @@ def transform(self, func, *args, **kwargs):
         Each subframe is endowed the attribute 'name' in case you need to know
         which group you are working on.
 
-        Example
+        Examples
         --------
         >>> grouped = df.groupby(lambda x: mapping[x])
         >>> grouped.transform(lambda x: (x - x.mean()) / x.std())
diff --git a/pandas/io/excel.py b/pandas/io/excel.py
@@ -9,10 +9,6 @@
 from itertools import izip
 import numpy as np
 
-from pandas.core.index import Index, MultiIndex
-from pandas.core.frame import DataFrame
-import pandas.core.common as com
-from pandas.util import py3compat
 from pandas.io.parsers import TextParser
 from pandas.tseries.period import Period
 import json
@@ -21,8 +17,7 @@ def read_excel(path_or_buf, sheetname, header=0, skiprows=None, skip_footer=0,
                index_col=None, parse_cols=None, parse_dates=False,
                date_parser=None, na_values=None, thousands=None, chunksize=None,
                kind=None, **kwds):
-    """
-    Read Excel table into DataFrame
+    """Read an Excel table into a pandas DataFrame
 
     Parameters
     ----------
@@ -38,23 +33,30 @@ def read_excel(path_or_buf, sheetname, header=0, skiprows=None, skip_footer=0,
         Column to use as the row labels of the DataFrame. Pass None if
         there is no such column
     parse_cols : int or list, default None
-        If None then parse all columns,
-        If int then indicates last column to be parsed
-        If list of ints then indicates list of column numbers to be parsed
-        If string then indicates comma separated list of column names and
-            column ranges (e.g. "A:E" or "A,C,E:F")
+        * If None then parse all columns,
+        * If int then indicates last column to be parsed
+        * If list of ints then indicates list of column numbers to be parsed
+        * If string then indicates comma separated list of column names and
+          column ranges (e.g. "A:E" or "A,C,E:F")
     na_values : list-like, default None
         List of additional strings to recognize as NA/NaN
 
     Returns
     -------
     parsed : DataFrame
+        DataFrame from the passed in Excel file
     """
     return ExcelFile(path_or_buf,kind=kind).parse(sheetname=sheetname,
-                                                  header=0, skiprows=None, skip_footer=0,
-                                                  index_col=None, parse_cols=None, parse_dates=False,
-                                                  date_parser=None, na_values=None, thousands=None, chunksize=None,
-                                                  kind=None, **kwds)
+                                                  header=0, skiprows=None,
+                                                  skip_footer=0,
+                                                  index_col=None,
+                                                  parse_cols=None,
+                                                  parse_dates=False,
+                                                  date_parser=None,
+                                                  na_values=None,
+                                                  thousands=None,
+                                                  chunksize=None, kind=None,
+                                                  **kwds)
 
 class ExcelFile(object):
     """
@@ -90,8 +92,7 @@ def parse(self, sheetname, header=0, skiprows=None, skip_footer=0,
               index_col=None, parse_cols=None, parse_dates=False,
               date_parser=None, na_values=None, thousands=None, chunksize=None,
               **kwds):
-        """
-        Read Excel table into DataFrame
+        """Read an Excel table into DataFrame
 
         Parameters
         ----------
@@ -107,17 +108,19 @@ def parse(self, sheetname, header=0, skiprows=None, skip_footer=0,
             Column to use as the row labels of the DataFrame. Pass None if
             there is no such column
         parse_cols : int or list, default None
-            If None then parse all columns,
-            If int then indicates last column to be parsed
-            If list of ints then indicates list of column numbers to be parsed
-            If string then indicates comma separated list of column names and
-                column ranges (e.g. "A:E" or "A,C,E:F")
+            * If None then parse all columns
+            * If int then indicates last column to be parsed
+            * If list of ints then indicates list of column numbers to be
+              parsed
+            * If string then indicates comma separated list of column names and
+              column ranges (e.g. "A:E" or "A,C,E:F")
         na_values : list-like, default None
             List of additional strings to recognize as NA/NaN
 
         Returns
         -------
         parsed : DataFrame
+            DataFrame parsed from the Excel file
         """
 
         # has_index_names: boolean, default False
diff --git a/pandas/io/pytables.py b/pandas/io/pytables.py
@@ -386,9 +386,6 @@ def select(self, key, where=None, start=None, stop=None, columns=None, iterator=
         Parameters
         ----------
         key : object
-
-        Optional Parameters
-        -------------------
         where : list of Term (or convertable) objects, optional
         start : integer (defaults to None), row number to start selection
         stop  : integer (defaults to None), row number to stop selection
@@ -421,9 +418,6 @@ def select_as_coordinates(self, key, where=None, start=None, stop=None, **kwargs
         Parameters
         ----------
         key : object
-
-        Optional Parameters
-        -------------------
         where : list of Term (or convertable) objects, optional
         start : integer (defaults to None), row number to start selection
         stop  : integer (defaults to None), row number to stop selection
@@ -551,9 +545,6 @@ def remove(self, key, where=None, start=None, stop=None):
         ----------
         key : string
             Node to remove or delete rows from
-
-        Optional Parameters
-        -------------------
         where : list of Term (or convertable) objects, optional
         start : integer (defaults to None), row number to start selection
         stop  : integer (defaults to None), row number to stop selection
@@ -602,9 +593,6 @@ def append(self, key, value, columns=None, **kwargs):
         ----------
         key : object
         value : {Series, DataFrame, Panel, Panel4D}
-
-        Optional Parameters
-        -------------------
         data_columns : list of columns to create as data columns, or True to use all columns
         min_itemsize : dict of columns that specify minimum string sizes
         nan_rep      : string to use as string nan represenation
@@ -3276,30 +3264,29 @@ def _need_convert(kind):
     return False
 
 class Term(object):
-    """ create a term object that holds a field, op, and value
+    """create a term object that holds a field, op, and value
 
-        Parameters
-        ----------
-        field : dict, string term expression, or the field to operate (must be a valid index/column type of DataFrame/Panel)
-        op    : a valid op (defaults to '=') (optional)
-                >, >=, <, <=, =, != (not equal) are allowed
-        value : a value or list of values (required)
-        queryables : a kinds map (dict of column name -> kind), or None i column is non-indexable
+    Parameters
+    ----------
+    field : dict, string term expression, or the field to operate (must be a valid index/column type of DataFrame/Panel)
+    op    : a valid op (defaults to '=') (optional)
+            >, >=, <, <=, =, != (not equal) are allowed
+    value : a value or list of values (required)
+    queryables : a kinds map (dict of column name -> kind), or None i column is non-indexable
 
-        Returns
-        -------
-        a Term object
-
-        Examples
-        --------
-        Term(dict(field = 'index', op = '>', value = '20121114'))
-        Term('index', '20121114')
-        Term('index', '>', '20121114')
-        Term('index', ['20121114','20121114'])
-        Term('index', datetime(2012,11,14))
-        Term('major_axis>20121114')
-        Term('minor_axis', ['A','B'])
+    Returns
+    -------
+    a Term object
 
+    Examples
+    --------
+    >>> Term(dict(field = 'index', op = '>', value = '20121114'))
+    >>> Term('index', '20121114')
+    >>> Term('index', '>', '20121114')
+    >>> Term('index', ['20121114','20121114'])
+    >>> Term('index', datetime(2012,11,14))
+    >>> Term('major_axis>20121114')
+    >>> Term('minor_axis', ['A','B'])
     """
 
     _ops = ['<=', '<', '>=', '>', '!=', '==', '=']
diff --git a/pandas/tseries/frequencies.py b/pandas/tseries/frequencies.py
