Repository: pandas-dev/pandas

Issue:
DOC: Add documentation for freq='infer' option of DatetimeIndex and TimedeltaIndex constructors
There currently doesn't appear to be any information regarding passing `freq='infer'` to the `DatetimeIndex` or `TimedeltaIndex` constructors; I only became aware of this option from reading over the code.  Would be nice to document this feature in the docstrings for `DatetimeIndex` and `TimedeltaIndex`.  Possibly in `timeseries.rst` and `timdeltas.rst` too. 

Essentially, this allows users to set the frequency of the index as the inferred frequency upon creation:
```python
In [2]: pd.DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'], freq='infer')
Out[2]: DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'], dtype='datetime64[ns]', freq='2D')
```

Note that the frequency is not automatically inferred if nothing is passed to the `freq` parameter:
```python
In [3]: pd.DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'])
Out[3]: DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'], dtype='datetime64[ns]', freq=None)
```

Similar example with `TimedeltaIndex`:
```python
In [4]: pd.TimedeltaIndex(['0 days', '10 days', '20 days'], freq='infer')
Out[4]: TimedeltaIndex(['0 days', '10 days', '20 days'], dtype='timedelta64[ns]', freq='10D')

In [5]: pd.TimedeltaIndex(['0 days', '10 days', '20 days'])
Out[5]: TimedeltaIndex(['0 days', '10 days', '20 days'], dtype='timedelta64[ns]', freq=None)
```


Discussion:
Hi jschendel, I am newbie to opensource. Can I work on this.?
@kirakrishnan : Sure, go for it!
Thanks @jschendel. This is my understanding. Please tell me if I am wrong

currently the documentation for `freq` in `class DatetimeIndex()`(pandas/core/indexes/datetimes.py)
freq : string or pandas offset object, optional
      One of pandas date offset strings or corresponding objects

And the documentation for `freq` in `class TimedeltaIndex`(pandas/core/indexes/timedeltas.py)
freq: a frequency for the index, optional

And I need to update documentation this way
freq : 'infer', string or pandas offset object, optional
	infer allows users to set the frequency of the index as the inferred frequency upon creation
      One of pandas date offset strings or corresponding objects

freq: 'infer'
	infer allows users to set the frequency of the index as the inferred frequency upon creation


adding this example under `Conversions` in `timedeltas.rst`
In [4]: pd.TimedeltaIndex(['0 days', '10 days', '20 days'], freq='infer')
Out[4]: TimedeltaIndex(['0 days', '10 days', '20 days'], dtype='timedelta64[ns]', freq='10D')

In [5]: pd.TimedeltaIndex(['0 days', '10 days', '20 days'])
Out[5]: TimedeltaIndex(['0 days', '10 days', '20 days'], dtype='timedelta64[ns]', freq=None)

adding this example under `Generating Ranges of Timestamps` in `timeseries.rst`
In [2]: pd.DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'], freq='infer')
Out[2]: DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'], dtype='datetime64[ns]', freq='2D')

In [3]: pd.DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'])
Out[3]: DatetimeIndex(['2018-01-01', '2018-01-03', '2018-01-05'], dtype='datetime64[ns]', freq=None)
Yes, that's more or less what to do.  A few small adjustments:

For the `DatetimeIndex` docstring, I'd leave the `freq` type line as-is:
```
freq : string or pandas offset object, optional
```
And add an additional sentence to the description along the lines of (modify the wording as you see fit): 
```
One of pandas date offset strings or corresponding objects. The string 'infer' 
can be passed in order to...
```

For the `TimedeltaIndex` docstring you can just copy and paste the `freq` portion to be identical to the `DatetimeIndex` docstring.

For `timedeltas.rst`, you can put this in the "TimedeltaIndex" section, immediately after the first example where the `TimedeltaIndex` constructor is used (so your changes would start around line 365).

Not entirely sure where this should go in `timeseries.rst`, as it looks like the convention is generally to use `pd.to_datetime`.  You can maybe put it at the end of the "Converting to Timestamps" section.  You can say something like: 
```
You can also use the `DatetimeIndex` constructor directly:
```
and first give an example of the regular (`freq` omitted) usage, followed by an example with `freq='infer'`.  So, a setup similar to what your modified "TimedelaIndex" section will look like.



Resolving patch:
diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py
--- a/pandas/core/indexes/datetimes.py
+++ b/pandas/core/indexes/datetimes.py
@@ -186,7 +186,10 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin,
     copy  : bool
         Make a copy of input ndarray
     freq : string or pandas offset object, optional
-        One of pandas date offset strings or corresponding objects
+        One of pandas date offset strings or corresponding objects. The string
+        'infer' can be passed in order to set the frequency of the index as the
+        inferred frequency upon creation
+
     start : starting value, datetime-like, optional
         If data is None, start is used as the start point in generating regular
         timestamp data.
diff --git a/pandas/core/indexes/timedeltas.py b/pandas/core/indexes/timedeltas.py
--- a/pandas/core/indexes/timedeltas.py
+++ b/pandas/core/indexes/timedeltas.py
@@ -107,7 +107,10 @@ class TimedeltaIndex(DatetimeIndexOpsMixin, TimelikeOps, Int64Index):
         Optional timedelta-like data to construct index with
     unit: unit of the arg (D,h,m,s,ms,us,ns) denote the unit, optional
         which is an integer/float number
-    freq: a frequency for the index, optional
+    freq : string or pandas offset object, optional
+        One of pandas date offset strings or corresponding objects. The string
+        'infer' can be passed in order to set the frequency of the index as the
+        inferred frequency upon creation
     copy  : bool
         Make a copy of input ndarray
     start : starting value, timedelta-like, optional


Test patch: