Repository: pandas-dev/pandas

Issue:
Docs for read_html : parse_dates
`parse_dates` should have a little more documentation (I did look at docs on read_csv as well).

It is not clear to me what the default value of parse_dates is.

Alson on read_html is listed as "bool" whereas on read_csv as "boolean, list of ints or names, list of lists, or dict".

I am not sure what setting parse_dates=False does.



Discussion:
> It is not clear to me what the default value of parse_dates is.

The default values of API docs are shown in the function signature. See [here](http://pandas.pydata.org/pandas-docs/dev/generated/pandas.io.html.read_html.html#pandas.io.html.read_html).

> Alson on read_html is listed as "bool" whereas on read_csv as "boolean, list of ints or names, list of lists, or dict".

I'll fix this and refer the user to the `read_csv` docs.

> I am not sure what setting parse_dates=False does.

What do you think it does? It simply won't try to parse dates/times and will leave them as strings in the result.

Anyway to make that into a link to read_csv in the function signature?
 That'd be nice, though maybe not possible?

Sure ... i think you can refer to other API docs in docstrings

@cpcloud re: "parse_dates=False", I don't understand what is going on here then (see column 2 for example):

```
In [7]: pd.read_html("http://pastebin.com/raw.php?i=7mAF0Ei6",parse_dates=False)[0]
Out[7]: 
                                                   0   1                   2      3                   4    5                   6    7                   8                   9    10   11                  12   13
0                                                 NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
1                                                 NaN NaN 2013-01-01 00:00:00    NaN 2012-01-01 00:00:00  NaN 2013-01-01 00:00:00  NaN 2012-01-01 00:00:00                 NaT  NaN  NaN                 NaT  NaN
2                                                 NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
3                                        Net revenue: NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
4                                           Notebooks NaN                 NaT   3718                 NaT    $                 NaT  NaN                 NaT                 NaT  NaN    $                 NaT  NaN
5                                            Desktops NaN                 NaT   3103                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
6                                        Workstations NaN                 NaT    521                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
7                                               Other NaN                 NaT    242                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
8                                                 NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
9                                    Personal Systems NaN                 NaT   7584                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
10                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
11                                           Supplies NaN                 NaT   4122                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
12                                Commercial Hardware NaN                 NaT   1398                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
13                                  Consumer Hardware NaN                 NaT    561                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
14                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
15                                           Printing NaN                 NaT   6081                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
16                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
17                Printing and Personal Systems Group NaN                 NaT  13665                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
18                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
19                          Industry Standard Servers NaN                 NaT   2806                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
20                                Technology Services NaN                 NaT   2272                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
21                                            Storage NaN                 NaT    857                 NaT  NaN                 NaT  NaN                 NaT 1690-01-01 00:00:00  NaN  NaN 1945-01-01 00:00:00  NaN
22                                         Networking NaN                 NaT    618                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
23                          Business Critical Systems NaN                 NaT    266                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
24                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
25                                   Enterprise Group NaN                 NaT   6819                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
26                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
27              Infrastructure Technology Outsourcing NaN                 NaT   3721                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
28                  Application and Business Services NaN                 NaT   2278                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
29                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
30                                Enterprise Services NaN                 NaT   5999                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
31                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
32                                           Software NaN                 NaT    941                 NaT  NaN                 NaT  NaN                 NaT 1867-01-01 00:00:00  NaN  NaN 1916-01-01 00:00:00  NaN
33                              HP Financial Services NaN                 NaT    881                 NaT  NaN                 NaT  NaN                 NaT 1838-01-01 00:00:00  NaN  NaN 1918-01-01 00:00:00  NaN
34                              Corporate Investments NaN                 NaT     10                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
35                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
36                                     Total segments NaN                 NaT  28315                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
37                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
38  Eliminations of intersegment net revenue and o... NaN                 NaT   (733                 NaT  NaN                 NaT    )                 NaT                 NaT    )  NaN                 NaT    )
39                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
40                  Total HP consolidated net revenue NaN                 NaT  27582                 NaT    $                 NaT  NaN                 NaT                 NaT  NaN    $                 NaT  NaN
41                                                NaN NaN                 NaT    NaN                 NaT  NaN                 NaT  NaN                 NaT                 NaT  NaN  NaN                 NaT  NaN
```

that's because `infer_types=True`, and the main reason `infer_types` will have no effect in 0.14. As you can see they conflict with each other because `parse_dates=False` is overridden by `infer_types=True` which performs a hard conversion of dates ... what do you get when you pass `parse_dates=False` and `infer_types=False`?

That looks better:

```
In [9]: pd.read_html("http://pastebin.com/raw.php?i=7mAF0Ei6",infer_types=False)[0]
Out[9]: 
                                                   0    1   \
0                                                 nan  nan   
1                                                 nan  nan   
2                                                 nan  nan   
3                                        Net revenue:  nan   
4                                           Notebooks  nan   
5                                            Desktops  nan   
6                                        Workstations  nan   
7                                               Other  nan   
8                                                 nan  nan   
9                                    Personal Systems  nan   
10                                                nan  nan   
11                                           Supplies  nan   
12                                Commercial Hardware  nan   
13                                  Consumer Hardware  nan   
14                                                nan  nan   
15                                           Printing  nan   
16                                                nan  nan   
17                Printing and Personal Systems Group  nan   
18                                                nan  nan   
19                          Industry Standard Servers  nan   
20                                Technology Services  nan   
21                                            Storage  nan   
22                                         Networking  nan   
23                          Business Critical Systems  nan   
24                                                nan  nan   
25                                   Enterprise Group  nan   
26                                                nan  nan   
27              Infrastructure Technology Outsourcing  nan   
28                  Application and Business Services  nan   
29                                                nan  nan   
30                                Enterprise Services  nan   
31                                                nan  nan   
32                                           Software  nan   
33                              HP Financial Services  nan   
34                              Corporate Investments  nan   
35                                                nan  nan   
36                                     Total segments  nan   
37                                                nan  nan   
38  Eliminations of intersegment net revenue and o...  nan   
39                                                nan  nan   
40                  Total HP consolidated net revenue  nan   
41                                                nan  nan   

                             2      3                          4    5      6   \
0   Three months ended April 30    nan  Six months ended April 30  nan    nan   
1                          2013    nan                       2012  nan   2013   
2                   In millions    nan                        nan  nan    nan   
3                           nan    nan                        nan  nan    nan   
4                             $   3718                        nan    $   4900   
5                           nan   3103                        nan  nan   3827   
6                           nan    521                        nan  nan    537   
7                           nan    242                        nan  nan    206   
8                           nan    nan                        nan  nan    nan   
9                           nan   7584                        nan  nan   9470   
10                          nan    nan                        nan  nan    nan   
11                          nan   4122                        nan  nan   4060   
12                          nan   1398                        nan  nan   1479   
13                          nan    561                        nan  nan    593   
14                          nan    nan                        nan  nan    nan   
15                          nan   6081                        nan  nan   6132   
16                          nan    nan                        nan  nan    nan   
17                          nan  13665                        nan  nan  15602   
18                          nan    nan                        nan  nan    nan   
19                          nan   2806                        nan  nan   3186   
20                          nan   2272                        nan  nan   2335   
21                          nan    857                        nan  nan    990   
22                          nan    618                        nan  nan    614   
23                          nan    266                        nan  nan    421   
24                          nan    nan                        nan  nan    nan   
25                          nan   6819                        nan  nan   7546   
26                          nan    nan                        nan  nan    nan   
27                          nan   3721                        nan  nan   3954   
28                          nan   2278                        nan  nan   2535   
29                          nan    nan                        nan  nan    nan   
30                          nan   5999                        nan  nan   6489   
31                          nan    nan                        nan  nan    nan   
32                          nan    941                        nan  nan    970   
33                          nan    881                        nan  nan    968   
34                          nan     10                        nan  nan      7   
35                          nan    nan                        nan  nan    nan   
36                          nan  28315                        nan  nan  31582   
37                          nan    nan                        nan  nan    nan   
38                          nan   (733                          )  nan   (889   
39                          nan    nan                        nan  nan    nan   
40                            $  27582                        nan    $  30693   
41                          nan    nan                        nan  nan    nan   

     7     8       9    10   11      12   13  
0   nan   nan     nan  nan  nan     nan  nan  
1   nan  2012     nan  nan  nan     nan  nan  
2   nan   nan     nan  nan  nan     nan  nan  
3   nan   nan     nan  nan  nan     nan  nan  
4   nan     $    7846  nan    $    9842  nan  
5   nan   nan    6424  nan  nan    7033  nan  
6   nan   nan    1056  nan  nan    1072  nan  
7   nan   nan     462  nan  nan     415  nan  
8   nan   nan     nan  nan  nan     nan  nan  
9   nan   nan   15788  nan  nan   18362  nan  
10  nan   nan     nan  nan  nan     nan  nan  
11  nan   nan    8015  nan  nan    8139  nan  
12  nan   nan    2752  nan  nan    2968  nan  
13  nan   nan    1240  nan  nan    1283  nan  
14  nan   nan     nan  nan  nan     nan  nan  
15  nan   nan   12007  nan  nan   12390  nan  
16  nan   nan     nan  nan  nan     nan  nan  
17  nan   nan   27795  nan  nan   30752  nan  
18  nan   nan     nan  nan  nan     nan  nan  
19  nan   nan    5800  nan  nan    6258  nan  
20  nan   nan    4515  nan  nan    4599  nan  
21  nan   nan    1690  nan  nan    1945  nan  
22  nan   nan    1226  nan  nan    1200  nan  
23  nan   nan     572  nan  nan     826  nan  
24  nan   nan     nan  nan  nan     nan  nan  
25  nan   nan   13803  nan  nan   14828  nan  
26  nan   nan     nan  nan  nan     nan  nan  
27  nan   nan    7457  nan  nan    7934  nan  
28  nan   nan    4461  nan  nan    4926  nan  
29  nan   nan     nan  nan  nan     nan  nan  
30  nan   nan   11918  nan  nan   12860  nan  
31  nan   nan     nan  nan  nan     nan  nan  
32  nan   nan    1867  nan  nan    1916  nan  
33  nan   nan    1838  nan  nan    1918  nan  
34  nan   nan      14  nan  nan      37  nan  
35  nan   nan     nan  nan  nan     nan  nan  
36  nan   nan   57235  nan  nan   62311  nan  
37  nan   nan     nan  nan  nan     nan  nan  
38    )   nan  (1,294    )  nan  (1,582    )  
39  nan   nan     nan  nan  nan     nan  nan  
40  nan     $   55941  nan    $   60729  nan  
41  nan   nan     nan  nan  nan     nan  nan  
```

@cpcloud It might be worth adding a note to the docs about the interaction of these two parameters. 

good idea

@cancan101 BTW thanks for being so vocal about your `read_html` experience! Always appreciate user feedback!


Resolving patch:
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -1982,29 +1982,35 @@ def interpolate(self, method='linear', axis=0, limit=None, inplace=False,
 
         Parameters
         ----------
-        method : {'linear', 'time', 'values', 'index' 'nearest',
-                  'zero', 'slinear', 'quadratic', 'cubic',
-                  'barycentric', 'krogh', 'polynomial', 'spline'
-                  'piecewise_polynomial', 'pchip'}
-            'linear': ignore the index and treat the values as equally spaced. default
-            'time': interpolation works on daily and higher resolution
+        method : {'linear', 'time', 'values', 'index' 'nearest', 'zero',
+                  'slinear', 'quadratic', 'cubic', 'barycentric', 'krogh',
+                  'polynomial', 'spline' 'piecewise_polynomial', 'pchip'}
+
+            * 'linear': ignore the index and treat the values as equally
+               spaced. default
+            * 'time': interpolation works on daily and higher resolution
                 data to interpolate given length of interval
-            'index': use the actual numerical values of the index
-            'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'barycentric',
-            'polynomial' is passed to `scipy.interpolate.interp1d` with the order given
-                both 'polynomial' and 'spline' requre that you also specify and order (int)
-                e.g. df.interpolate(method='polynomial', order=4)
-            'krogh', 'piecewise_polynomial', 'spline', and 'pchip' are all wrappers
-            around the scipy interpolation methods of similar names. See the
-            scipy documentation for more on their behavior:
-            http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation
-            http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html
+            * 'index': use the actual numerical values of the index
+            * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic',
+              'barycentric', 'polynomial' is passed to
+              `scipy.interpolate.interp1d` with the order given both
+              'polynomial' and 'spline' requre that you also specify and order
+              (int) e.g. df.interpolate(method='polynomial', order=4)
+            * 'krogh', 'piecewise_polynomial', 'spline', and 'pchip' are all
+               wrappers around the scipy interpolation methods of similar
+               names. See the scipy documentation for more on their behavior:
+               http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation
+               http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html
+
         axis : {0, 1}, default 0
-            0: fill column-by-column
-            1: fill row-by-row
-        limit : int, default None. Maximum number of consecutive NaNs to fill.
+            * 0: fill column-by-column
+            * 1: fill row-by-row
+        limit : int, default None.
+            Maximum number of consecutive NaNs to fill.
         inplace : bool, default False
+            Update the NDFrame in place if possible.
         downcast : optional, 'infer' or None, defaults to 'infer'
+            Downcast dtypes if possible.
 
         Returns
         -------
diff --git a/pandas/core/panel.py b/pandas/core/panel.py
--- a/pandas/core/panel.py
+++ b/pandas/core/panel.py
@@ -391,8 +391,8 @@ def to_excel(self, path, na_rep='', engine=None, **kwargs):
             ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and
             ``io.excel.xlsm.writer``.
 
-        Keyword Arguments
-        -----------------
+        Other Parameters
+        ----------------
         float_format : string, default None
             Format string for floating point numbers
         cols : sequence, optional
@@ -409,6 +409,8 @@ def to_excel(self, path, na_rep='', engine=None, **kwargs):
         startow : upper left cell row to dump data frame
         startcol : upper left cell column to dump data frame
 
+        Notes
+        -----
         Keyword arguments (and na_rep) are passed to the ``to_excel`` method
         for each DataFrame written.
         """
diff --git a/pandas/io/html.py b/pandas/io/html.py
--- a/pandas/io/html.py
+++ b/pandas/io/html.py
@@ -782,7 +782,10 @@ def read_html(io, match='.+', flavor=None, header=None, index_col=None,
         latest information on table attributes for the modern web.
 
     parse_dates : bool, optional
-        See :func:`~pandas.read_csv` for details.
+        See :func:`~pandas.io.parsers.read_csv` for more details. In 0.13, this
+        parameter can sometimes interact strangely with ``infer_types``. If you
+        get a large number of ``NaT`` values in your results, consider passing
+        ``infer_types=False`` and manually converting types afterwards.
 
     tupleize_cols : bool, optional
         If ``False`` try to parse multiple header rows into a
@@ -824,12 +827,12 @@ def read_html(io, match='.+', flavor=None, header=None, index_col=None,
 
     See Also
     --------
-    pandas.read_csv
+    pandas.io.parsers.read_csv
     """
     if infer_types is not None:
         warnings.warn("infer_types will have no effect in 0.14", FutureWarning)
     else:
-        infer_types = True  # TODO: remove in 0.14
+        infer_types = True  # TODO: remove effect of this in 0.14
 
     # Type check here. We don't want to parse only to fail because of an
     # invalid value of an integer skiprows.


Test patch: