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

pandas/_libs/tslibs/nattype.pyx

@@ -478,11 +478,13 @@ class NaTType(_NaT):
         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

pandas/_libs/tslibs/timedeltas.pyx

@@ -820,7 +820,7 @@ cdef class _Timedelta(timedelta):
     def isoformat(self):
         """
         Format Timedelta as ISO 8601 Duration like
-        `P[n]Y[n]M[n]DT[n]H[n]M[n]S`, where the `[n]`s are replaced by the
+        ``P[n]Y[n]M[n]DT[n]H[n]M[n]S``, where the ``[n]`` s are replaced by the
         values. See https://en.wikipedia.org/wiki/ISO_8601#Durations
 
         .. versionadded:: 0.20.0
@@ -881,7 +881,7 @@ class Timedelta(_Timedelta):
     Parameters
     ----------
     value : Timedelta, timedelta, np.timedelta64, string, or integer
-    unit : string, [D,h,m,s,ms,us,ns]
+    unit : string, {'ns', 'us', 'ms', 's', 'm', 'h', 'D'}, optional
         Denote the unit of the input, if input is an integer. Default 'ns'.
     days, seconds, microseconds,
     milliseconds, minutes, hours, weeks : numeric, optional

pandas/core/computation/eval.py

@@ -202,7 +202,7 @@ def eval(expr, parser='pandas', engine=None, truediv=True,
         you can use to inject an additional collection of namespaces to use for
         variable lookup. For example, this is used in the
         :meth:`~pandas.DataFrame.query` method to inject the
-        :attr:`~pandas.DataFrame.index` and :attr:`~pandas.DataFrame.columns`
+        ``DataFrame.index`` and ``DataFrame.columns``
         variables that refer to their respective :class:`~pandas.DataFrame`
         instance attributes.
     level : int, optional

pandas/core/config_init.py

@@ -392,8 +392,9 @@ def table_schema_cb(key):
     cf.register_option('sim_interactive', False, tc_sim_interactive_doc)
 
 use_inf_as_null_doc = """
-use_inf_as_null had been deprecated and will be removed in a future version.
-Use `use_inf_as_na` instead.
+: boolean
+    use_inf_as_null had been deprecated and will be removed in a future
+    version. Use `use_inf_as_na` instead.
 """
 
 use_inf_as_na_doc = """

pandas/core/frame.py

@@ -1692,7 +1692,7 @@ def to_html(self, buf=None, columns=None, col_space=None, header=True,
         classes : str or list or tuple, default None
             CSS class(es) to apply to the resulting html table
         escape : boolean, default True
-            Convert the characters <, >, and & to HTML-safe sequences.=
+            Convert the characters <, >, and & to HTML-safe sequences.
         max_rows : int, optional
             Maximum number of rows to show before truncating. If None, show
             all.
@@ -1703,6 +1703,7 @@ def to_html(self, buf=None, columns=None, col_space=None, header=True,
             Character recognized as decimal separator, e.g. ',' in Europe
 
             .. versionadded:: 0.18.0
+
         border : int
             A ``border=border`` attribute is included in the opening
             `<table>` tag. Default ``pd.options.html.border``.

pandas/core/generic.py

@@ -6278,6 +6278,7 @@ def truncate(self, before=None, after=None, axis=None, copy=True):
 
             * 0 or 'index': apply truncation to rows
             * 1 or 'columns': apply truncation to columns
+
             Default is stat axis for given data type (0 for Series and
             DataFrames, 1 for Panels)
         copy : boolean, default is True,

pandas/core/groupby.py

@@ -742,8 +742,8 @@ def _cumcount_array(self, ascending=True):
         ascending : bool, default True
             If False, number in reverse, from length of group - 1 to 0.
 
-        Note
-        ----
+        Notes
+        -----
         this is currently implementing sort=False
         (though the default is sort=True) for groupby in general
         """
@@ -1257,7 +1257,6 @@ def expanding(self, *args, **kwargs):
         return ExpandingGroupby(self, *args, **kwargs)
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def pad(self, limit=None):
         """
         Forward fill the values
@@ -1269,14 +1268,15 @@ def pad(self, limit=None):
 
         See Also
         --------
+        Series.pad
+        DataFrame.pad
         Series.fillna
         DataFrame.fillna
         """
         return self.apply(lambda x: x.ffill(limit=limit))
     ffill = pad
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def backfill(self, limit=None):
         """
         Backward fill the values
@@ -1288,6 +1288,8 @@ def backfill(self, limit=None):
 
         See Also
         --------
+        Series.backfill
+        DataFrame.backfill
         Series.fillna
         DataFrame.fillna
         """
@@ -1450,7 +1452,6 @@ def nth(self, n, dropna=None):
         return result
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def ngroup(self, ascending=True):
         """
         Number each group from 0 to the number of groups - 1.
@@ -1507,7 +1508,6 @@ def ngroup(self, ascending=True):
         See also
         --------
         .cumcount : Number the rows in each group.
-
         """
 
         self._set_group_selection()
@@ -1519,7 +1519,6 @@ def ngroup(self, ascending=True):
         return result
 
     @Substitution(name='groupby')
-    @Appender(_doc_template)
     def cumcount(self, ascending=True):
         """
         Number each item in each group from 0 to the length of that group - 1.

pandas/core/indexes/period.py

@@ -624,9 +624,9 @@ def to_timestamp(self, freq=None, how='start'):
 
         Parameters
         ----------
-        freq : string or DateOffset, default 'D' for week or longer, 'S'
-               otherwise
-            Target frequency
+        freq : string or DateOffset, optional
+            Target frequency. The default is 'D' for week or longer,
+            'S' otherwise
         how : {'s', 'e', 'start', 'end'}
 
         Returns
@@ -1039,8 +1039,8 @@ def tz_convert(self, tz):
         -------
         normalized : DatetimeIndex
 
-        Note
-        ----
+        Notes
+        -----
         Not currently implemented for PeriodIndex
         """
         raise NotImplementedError("Not yet implemented for PeriodIndex")
@@ -1063,8 +1063,8 @@ def tz_localize(self, tz, infer_dst=False):
         -------
         localized : DatetimeIndex
 
-        Note
-        ----
+        Notes
+        -----
         Not currently implemented for PeriodIndex
         """
         raise NotImplementedError("Not yet implemented for PeriodIndex")