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

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

pandas/_libs/period.pyx

@@ -966,7 +966,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

@@ -263,19 +263,16 @@ class Timestamp(_Timestamp):
     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
-    ------------------------------------
+    Parameters
+    ----------
 
     .. versionadded:: 0.19.0
 
     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
+    hour, minute, second, microsecond : int, optional, default 0
+    tzinfo : datetime.tzinfo, optional, default None
     """
 
     @classmethod
@@ -593,11 +590,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
@@ -1916,7 +1915,7 @@ class Timedelta(_Timedelta):
     Parameters
     ----------
     value : Timedelta, timedelta, np.timedelta64, string, or integer
-    unit : string, [D,h,m,s,ms,us,ns]
+    unit : string, ``[D,h,m,s,ms,us,ns]``
         Denote the unit of the input, if input is an integer. Default 'ns'.
     days, seconds, microseconds,
     milliseconds, minutes, hours, weeks : numeric, optional

pandas/_libs/tslibs/timedeltas.pyx

@@ -575,7 +575,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

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/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

@@ -6276,6 +6276,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
         """

pandas/core/indexes/period.py

@@ -623,9 +623,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
@@ -1038,8 +1038,8 @@ def tz_convert(self, tz):
         -------
         normalized : DatetimeIndex
 
-        Note
-        ----
+        Notes
+        -----
         Not currently implemented for PeriodIndex
         """
         raise NotImplementedError("Not yet implemented for PeriodIndex")
@@ -1062,8 +1062,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")

pandas/io/formats/format.py

@@ -84,12 +84,23 @@
                              "match-parent", "initial", "unset")
 
 justify_docstring = """
-    justify : {'left', 'right', 'center', 'justify',
-               'justify-all', 'start', 'end', 'inherit',
-               'match-parent', 'initial', 'unset'}, default None
+    justify : str, default None
         How to justify the column labels. If None uses the option from
         the print configuration (controlled by set_option), 'right' out
-        of the box."""
+        of the box. Valid values are
+
+        * left
+        * right
+        * center
+        * justify
+        * justify-all
+        * start
+        * end
+        * inherit
+        * match-parent
+        * initial
+        * unset
+"""
 
 return_docstring = """
 

setup.py

@@ -225,8 +225,8 @@ def build_extensions(self):
 of the analysis into a form suitable for plotting or tabular display. pandas is
 the ideal tool for all of these tasks.
 
-Note
-----
+Notes
+-----
 Windows binaries built against NumPy 1.8.1
 """