DOC: Add linspace range behavior to the timeseries/timedeltas/interval docs (#21114)

* DOC: Add linspace range behavior to the timeseries/timedeltas/interval docs

Author: jschendel

doc/source/advanced.rst

@@ -924,6 +924,55 @@ bins, with ``NaN`` representing a missing value similar to other dtypes.
 
    pd.cut([0, 3, 5, 1], bins=c.categories)
 
+
+Generating Ranges of Intervals
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If we need intervals on a regular frequency, we can use the :func:`interval_range` function
+to create an ``IntervalIndex`` using various combinations of ``start``, ``end``, and ``periods``.
+The default frequency for ``interval_range`` is a 1 for numeric intervals, and calendar day for
+datetime-like intervals:
+
+.. ipython:: python
+
+   pd.interval_range(start=0, end=5)
+
+   pd.interval_range(start=pd.Timestamp('2017-01-01'), periods=4)
+
+   pd.interval_range(end=pd.Timedelta('3 days'), periods=3)
+
+The ``freq`` parameter can used to specify non-default frequencies, and can utilize a variety
+of :ref:`frequency aliases <timeseries.offset_aliases>` with datetime-like intervals:
+
+.. ipython:: python
+
+   pd.interval_range(start=0, periods=5, freq=1.5)
+
+   pd.interval_range(start=pd.Timestamp('2017-01-01'), periods=4, freq='W')
+
+   pd.interval_range(start=pd.Timedelta('0 days'), periods=3, freq='9H')
+
+Additionally, the ``closed`` parameter can be used to specify which side(s) the intervals
+are closed on.  Intervals are closed on the right side by default.
+
+.. ipython:: python
+
+   pd.interval_range(start=0, end=4, closed='both')
+
+   pd.interval_range(start=0, end=4, closed='neither')
+
+.. versionadded:: 0.23.0
+
+Specifying ``start``, ``end``, and ``periods`` will generate a range of evenly spaced
+intervals from ``start`` to ``end`` inclusively, with ``periods`` number of elements
+in the resulting ``IntervalIndex``:
+
+.. ipython:: python
+
+   pd.interval_range(start=0, end=6, periods=4)
+
+   pd.interval_range(pd.Timestamp('2018-01-01'), pd.Timestamp('2018-02-28'), periods=3)
+
 Miscellaneous indexing FAQ
 --------------------------
 

doc/source/timedeltas.rst

@@ -352,8 +352,8 @@ You can convert a ``Timedelta`` to an `ISO 8601 Duration`_ string with the
 TimedeltaIndex
 --------------
 
-To generate an index with time delta, you can use either the ``TimedeltaIndex`` or
-the ``timedelta_range`` constructor.
+To generate an index with time delta, you can use either the :class:`TimedeltaIndex` or
+the :func:`timedelta_range` constructor.
 
 Using ``TimedeltaIndex`` you can pass string-like, ``Timedelta``, ``timedelta``,
 or ``np.timedelta64`` objects. Passing ``np.nan/pd.NaT/nat`` will represent missing values.
@@ -363,13 +363,47 @@ or ``np.timedelta64`` objects. Passing ``np.nan/pd.NaT/nat`` will represent miss
    pd.TimedeltaIndex(['1 days', '1 days, 00:00:05',
                      np.timedelta64(2,'D'), datetime.timedelta(days=2,seconds=2)])
 
-Similarly to ``date_range``, you can construct regular ranges of a ``TimedeltaIndex``:
+Generating Ranges of Time Deltas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Similar to :func:`date_range`, you can construct regular ranges of a ``TimedeltaIndex``
+using :func:`timedelta_range`.  The default frequency for ``timedelta_range`` is 
+calendar day:
+
+.. ipython:: python
+
+   pd.timedelta_range(start='1 days', periods=5)
+
+Various combinations of ``start``, ``end``, and ``periods`` can be used with
+``timedelta_range``:
+
+.. ipython:: python
+
+   pd.timedelta_range(start='1 days', end='5 days')
+
+   pd.timedelta_range(end='10 days', periods=4)
+
+The ``freq`` parameter can passed a variety of :ref:`frequency aliases <timeseries.offset_aliases>`:
 
 .. ipython:: python
 
-   pd.timedelta_range(start='1 days', periods=5, freq='D')
    pd.timedelta_range(start='1 days', end='2 days', freq='30T')
 
+   pd.timedelta_range(start='1 days', periods=5, freq='2D5H')
+
+
+.. versionadded:: 0.23.0
+
+Specifying ``start``, ``end``, and ``periods`` will generate a range of evenly spaced
+timedeltas from ``start`` to ``end`` inclusively, with ``periods`` number of elements
+in the resulting ``TimedeltaIndex``:
+
+.. ipython:: python
+
+   pd.timedelta_range('0 days', '4 days', periods=5)
+
+   pd.timedelta_range('0 days', '4 days', periods=10)
+
 Using the TimedeltaIndex
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/timeseries.rst

@@ -393,6 +393,18 @@ of those specified will not be generated:
 
    pd.bdate_range(start=start, periods=20)
 
+.. versionadded:: 0.23.0
+
+Specifying ``start``, ``end``, and ``periods`` will generate a range of evenly spaced
+dates from ``start`` to ``end`` inclusively, with ``periods`` number of elements in the
+resulting ``DatetimeIndex``:
+
+.. ipython:: python
+
+   pd.date_range('2018-01-01', '2018-01-05', periods=5)
+
+   pd.date_range('2018-01-01', '2018-01-05', periods=10)
+
 .. _timeseries.custom-freq-ranges:
 
 Custom Frequency Ranges