DOC: Fix various warnings (#18083)

* DOC: Fix various warnings

I'm trying to get our doc build cleaned up. Just fixing warnings in this one
(mostly formatting, some references).

Section name warnings

Warning from computation.rst

Remove references to invalid index / columns

Various docstring fixups

More warnings

More warnings

* match NaT doc

* DOC: Remove duplicate sections

* More warnings

* fixup

Author: TomAugspurger

doc/source/api.rst

@@ -1822,7 +1822,7 @@ Interval
 Properties
 ~~~~~~~~~~
 .. autosummary::
-    :toctree generated/
+    :toctree: generated/
 
     Interval.closed
     Interval.closed_left
@@ -1843,7 +1843,7 @@ Timedelta
 Properties
 ~~~~~~~~~~
 .. autosummary::
-    :toctree generated/
+    :toctree: generated/
 
     Timedelta.asm8
     Timedelta.components
@@ -1860,7 +1860,7 @@ Properties
 Methods
 ~~~~~~~
 .. autosummary::
-    :toctree generated/
+    :toctree: generated/
 
     Timedelta.ceil
     Timedelta.floor

doc/source/computation.rst

@@ -670,6 +670,7 @@ columns of a ``DataFrame``:
 
 .. ipython:: python
    :okexcept:
+   :okwarning:
 
    r.agg({'A' : np.sum,
           'B' : lambda x: np.std(x, ddof=1)})

doc/source/conf.py

@@ -358,13 +358,12 @@
 # latex_use_modindex = True
 
 
-# Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'statsmodels': ('http://www.statsmodels.org/devel/', None),
     'matplotlib': ('http://matplotlib.org/', None),
-    'python': ('http://docs.python.org/3', None),
-    'numpy': ('http://docs.scipy.org/doc/numpy', None),
-    'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
     'py': ('https://pylib.readthedocs.io/en/latest/', None)
 }
 import glob
@@ -573,6 +572,15 @@ def remove_flags_docstring(app, what, name, obj, options, lines):
     if what == "attribute" and name.endswith(".flags"):
         del lines[:]
 
+
+suppress_warnings = [
+    # We "overwrite" autosummary with our PandasAutosummary, but
+    # still want the regular autosummary setup to run. So we just
+    # suppress this warning.
+    'app.add_directive'
+]
+
+
 def setup(app):
     app.connect("autodoc-process-docstring", remove_flags_docstring)
     app.add_autodocumenter(AccessorDocumenter)

doc/source/contributing.rst

@@ -60,7 +60,7 @@ Bug reports must:
 
 The issue will then show up to the *pandas* community and be open to comments/ideas from others.
 
-.. _contributing.github
+.. _contributing.github:
 
 Working with the code
 =====================

doc/source/io.rst

@@ -115,7 +115,7 @@ header : int or list of ints, default ``'infer'``
 names : array-like, default ``None``
   List of column names to use. If file contains no header row, then you should
   explicitly pass ``header=None``. Duplicates in this list will cause
-    a ``UserWarning`` to be issued.
+  a ``UserWarning`` to be issued.
 index_col :  int or sequence or ``False``, default ``None``
   Column to use as the row labels of the DataFrame. If a sequence is given, a
   MultiIndex is used. If you have a malformed file with delimiters at the end of

doc/source/whatsnew/v0.15.2.txt

@@ -163,7 +163,7 @@ Other enhancements:
      p.all()
 
 - Added support for ``utcfromtimestamp()``, ``fromtimestamp()``, and ``combine()`` on `Timestamp` class (:issue:`5351`).
-- Added Google Analytics (`pandas.io.ga`) basic documentation (:issue:`8835`). See `here<http://pandas.pydata.org/pandas-docs/version/0.15.2/remote_data.html#remote-data-ga>`__.
+- Added Google Analytics (`pandas.io.ga`) basic documentation (:issue:`8835`). See `here <http://pandas.pydata.org/pandas-docs/version/0.15.2/remote_data.html#remote-data-ga>`__.
 - ``Timedelta`` arithmetic returns ``NotImplemented`` in unknown cases, allowing extensions by custom classes (:issue:`8813`).
 - ``Timedelta`` now supports arithemtic with ``numpy.ndarray`` objects of the appropriate dtype (numpy 1.8 or newer only) (:issue:`8884`).
 - Added ``Timedelta.to_timedelta64()`` method to the public API (:issue:`8884`).

doc/source/whatsnew/v0.19.0.txt

@@ -216,6 +216,7 @@ contained the values ``[0, 3]``.
 **New behavior**:
 
 .. ipython:: python
+   :okwarning:
 
    pd.read_csv(StringIO(data), names=names)
 

doc/source/whatsnew/v0.20.0.txt

@@ -1375,6 +1375,7 @@ Convert to a MultiIndex DataFrame
 Convert to an xarray DataArray
 
 .. ipython:: python
+   :okwarning:
 
    p.to_xarray()
 

pandas/_libs/period.pyx

@@ -967,7 +967,7 @@ cdef class _Period(object):
     def strftime(self, fmt):
         """
         Returns the string representation of the :class:`Period`, depending
-        on the selected :keyword:`format`. :keyword:`format` must be a string
+        on the selected ``fmt``. ``fmt`` must be a string
         containing one or several directives.  The method recognizes the same
         directives as the :func:`time.strftime` function of the standard Python
         distribution, as well as the specific additional directives ``%f``,

pandas/_libs/tslib.pyx

@@ -237,15 +237,13 @@ _no_input = object()
 
 
 class Timestamp(_Timestamp):
-    """TimeStamp is the pandas equivalent of python's Datetime
+    """Pandas replacement for datetime.datetime
+
+    TimeStamp is the pandas equivalent of python's Datetime
     and is interchangable with it in most cases. It's the type used
     for the entries that make up a DatetimeIndex, and other timeseries
     oriented data structures in pandas.
 
-    There are essentially three calling conventions for the constructor. The
-    primary form accepts four parameters. They can be passed by position or
-    keyword.
-
     Parameters
     ----------
     ts_input : datetime-like, str, int, float
@@ -259,22 +257,32 @@ class Timestamp(_Timestamp):
     offset : str, DateOffset
         Deprecated, use freq
 
+    year, month, day : int
+        .. versionadded:: 0.19.0
+    hour, minute, second, microsecond : int, optional, default 0
+        .. versionadded:: 0.19.0
+    tzinfo : datetime.tzinfo, optional, default None
+        .. versionadded:: 0.19.0
+
+    Notes
+    -----
+    There are essentially three calling conventions for the constructor. The
+    primary form accepts four parameters. They can be passed by position or
+    keyword.
+
     The other two forms mimic the parameters from ``datetime.datetime``. They
     can be passed by either position or keyword, but not both mixed together.
 
-    :func:`datetime.datetime` Parameters
-    ------------------------------------
+    Examples
+    --------
+    >>> pd.Timestamp('2017-01-01T12')
+    Timestamp('2017-01-01 12:00:00')
 
-    .. versionadded:: 0.19.0
+    >>> pd.Timestamp(2017, 1, 1, 12)
+    Timestamp('2017-01-01 12:00:00')
 
-    year : int
-    month : int
-    day : int
-    hour : int, optional, default is 0
-    minute : int, optional, default is 0
-    second : int, optional, default is 0
-    microsecond : int, optional, default is 0
-    tzinfo : datetime.tzinfo, optional, default is None
+    >>> pd.Timestamp(year=2017, month=1, day=1, hour=12)
+    Timestamp('2017-01-01 12:00:00')
     """
 
     @classmethod
@@ -592,11 +600,13 @@ class Timestamp(_Timestamp):
         tz : string, pytz.timezone, dateutil.tz.tzfile or None
             Time zone for time which Timestamp will be converted to.
             None will remove timezone holding local time.
+
         ambiguous : bool, 'NaT', default 'raise'
             - bool contains flags to determine if time is dst or not (note
-            that this flag is only applicable for ambiguous fall dst dates)
+              that this flag is only applicable for ambiguous fall dst dates)
             - 'NaT' will return NaT for an ambiguous time
             - 'raise' will raise an AmbiguousTimeError for an ambiguous time
+
         errors : 'raise', 'coerce', default 'raise'
             - 'raise' will raise a NonExistentTimeError if a timestamp is not
                valid in the specified timezone (e.g. due to a transition from