DOC: Fix various warnings (#20509)

TomAugspurger · web-flow · commit 0c4e61192777 · 2018-03-28T21:31:37.000-05:00
diff --git a/doc/source/comparison_with_r.rst b/doc/source/comparison_with_r.rst
@@ -397,7 +397,7 @@ In Python, this list would be a list of tuples, so
    pd.DataFrame(a)
 
 For more details and examples see :ref:`the Into to Data Structures
-documentation <basics.dataframe.from_items>`.
+documentation <dsintro>`.
 
 |meltdf|_
 ~~~~~~~~~~~~~~~~
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
@@ -298,6 +298,11 @@ Some other important things to know about the docs:
   Standard**. Follow the :ref:`pandas docstring guide <docstring>` for detailed
   instructions on how to write a correct docstring.
 
+  .. toctree::
+     :maxdepth: 2
+
+     contributing_docstring.rst
+
 - The tutorials make heavy use of the `ipython directive
   <http://matplotlib.org/sampledoc/ipython_directive.html>`_ sphinx extension.
   This directive lets you put code in the documentation which will be run
@@ -900,7 +905,7 @@ Documenting your code
 Changes should be reflected in the release notes located in ``doc/source/whatsnew/vx.y.z.txt``.
 This file contains an ongoing change log for each release.  Add an entry to this file to
 document your fix, enhancement or (unavoidable) breaking change.  Make sure to include the
-GitHub issue number when adding your entry (using `` :issue:`1234` `` where `1234` is the
+GitHub issue number when adding your entry (using ``:issue:`1234``` where ``1234`` is the
 issue/pull request number).
 
 If your code is an enhancement, it is most likely necessary to add usage
@@ -1020,15 +1025,15 @@ release.  To submit a pull request:
 #. Click ``Send Pull Request``.
 
 This request then goes to the repository maintainers, and they will review
-the code. 
+the code.
 
 .. _contributing.update-pr:
 
 Updating your pull request
 --------------------------
 
 Based on the review you get on your pull request, you will probably need to make
-some changes to the code. In that case, you can make them in your branch, 
+some changes to the code. In that case, you can make them in your branch,
 add a new commit to that branch, push it to GitHub, and the pull request will be
 automatically updated.  Pushing them to GitHub again is done by::
 
@@ -1039,7 +1044,7 @@ This will automatically update your pull request with the latest code and restar
 
 Another reason you might need to update your pull request is to solve conflicts
 with changes that have been merged into the master branch since you opened your
-pull request. 
+pull request.
 
 To do this, you need to "merge upstream master" in your branch::
 
diff --git a/doc/source/cookbook.rst b/doc/source/cookbook.rst
@@ -411,6 +411,8 @@ Levels
 `Flatten Hierarchical columns
 <http://stackoverflow.com/questions/14507794/python-pandas-how-to-flatten-a-hierarchical-index-in-columns>`__
 
+.. _cookbook.missing_data:
+
 Missing Data
 ------------
 
diff --git a/doc/source/io.rst b/doc/source/io.rst
@@ -3862,6 +3862,8 @@ Then create the index when finished appending.
 
 See `here <http://stackoverflow.com/questions/17893370/ptrepack-sortby-needs-full-index>`__ for how to create a completely-sorted-index (CSI) on an existing store.
 
+.. _io.hdf5-query-data-columns:
+
 Query via Data Columns
 ++++++++++++++++++++++
 
diff --git a/doc/source/release.rst b/doc/source/release.rst
@@ -71,7 +71,7 @@ Highlights include:
 
 - Temporarily restore matplotlib datetime plotting functionality. This should
   resolve issues for users who relied implicitly on pandas to plot datetimes
-  with matplotlib. See :ref:`here <whatsnew_0211.special>`.
+  with matplotlib. See :ref:`here <whatsnew_0211.converters>`.
 - Improvements to the Parquet IO functions introduced in 0.21.0. See
   :ref:`here <whatsnew_0211.enhancements.parquet>`.
 
diff --git a/doc/source/whatsnew/v0.10.0.txt b/doc/source/whatsnew/v0.10.0.txt
@@ -409,7 +409,7 @@ N Dimensional Panels (Experimental)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Adding experimental support for Panel4D and factory functions to create n-dimensional named panels.
-:ref:`Docs <dsintro.panel4d>` for NDim. Here is a taste of what to expect.
+Here is a taste of what to expect.
 
 .. code-block:: ipython
 
diff --git a/doc/source/whatsnew/v0.16.1.txt b/doc/source/whatsnew/v0.16.1.txt
@@ -26,7 +26,7 @@ Highlights include:
 
 .. warning::
 
-   In pandas 0.17.0, the sub-package ``pandas.io.data`` will be removed in favor of a separately installable package. See :ref:`here for details <remote_data.pandas_datareader>` (:issue:`8961`)
+   In pandas 0.17.0, the sub-package ``pandas.io.data`` will be removed in favor of a separately installable package (:issue:`8961`).
 
 Enhancements
 ~~~~~~~~~~~~
diff --git a/doc/source/whatsnew/v0.23.0.txt b/doc/source/whatsnew/v0.23.0.txt
@@ -331,7 +331,7 @@ Other Enhancements
   :func:`pandas.api.extensions.register_series_accessor`, and
   :func:`pandas.api.extensions.register_index_accessor`, accessor for libraries downstream of pandas
   to register custom accessors like ``.cat`` on pandas objects. See
-  :ref:`Registering Custom Accessors <developer.register-accessors>` for more (:issue:`14781`).
+  :ref:`Registering Custom Accessors <extending.register-accessors>` for more (:issue:`14781`).
 
 - ``IntervalIndex.astype`` now supports conversions between subtypes when passed an ``IntervalDtype`` (:issue:`19197`)
 - :class:`IntervalIndex` and its associated constructor methods (``from_arrays``, ``from_breaks``, ``from_tuples``) have gained a ``dtype`` parameter (:issue:`19262`)
diff --git a/doc/source/whatsnew/v0.6.1.txt b/doc/source/whatsnew/v0.6.1.txt
@@ -16,12 +16,12 @@ New features
 - Add PyQt table widget to sandbox (:issue:`435`)
 - DataFrame.align can :ref:`accept Series arguments <basics.align.frame.series>`
   and an :ref:`axis option <basics.df_join>` (:issue:`461`)
-- Implement new :ref:`SparseArray <sparse.array>` and :ref:`SparseList <sparse.list>`
+- Implement new :ref:`SparseArray <sparse.array>` and `SparseList`
   data structures. SparseSeries now derives from SparseArray (:issue:`463`)
 - :ref:`Better console printing options <basics.console_output>` (:issue:`453`)
 - Implement fast :ref:`data ranking <computation.ranking>` for Series and
   DataFrame, fast versions of scipy.stats.rankdata (:issue:`428`)
-- Implement :ref:`DataFrame.from_items <basics.dataframe.from_items>` alternate
+- Implement `DataFrame.from_items` alternate
   constructor (:issue:`444`)
 - DataFrame.convert_objects method for :ref:`inferring better dtypes <basics.cast>`
   for object columns (:issue:`302`)
diff --git a/doc/source/whatsnew/v0.7.3.txt b/doc/source/whatsnew/v0.7.3.txt
@@ -22,7 +22,7 @@ New features
    from pandas.tools.plotting import scatter_matrix
    scatter_matrix(df, alpha=0.2)
 
-.. image:: _static/scatter_matrix_kde.png
+.. image:: savefig/scatter_matrix_kde.png
    :width: 5in
 
 - Add ``stacked`` argument to Series and DataFrame's ``plot`` method for
@@ -32,14 +32,14 @@ New features
 
    df.plot(kind='bar', stacked=True)
 
-.. image:: _static/bar_plot_stacked_ex.png
+.. image:: savefig/bar_plot_stacked_ex.png
    :width: 4in
 
 .. code-block:: python
 
    df.plot(kind='barh', stacked=True)
 
-.. image:: _static/barh_plot_stacked_ex.png
+.. image:: savefig/barh_plot_stacked_ex.png
    :width: 4in
 
 - Add log x and y :ref:`scaling options <visualization.basic>` to
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
@@ -1900,7 +1900,7 @@ def to_hdf(self, path_or_buf, key, **kwargs):
         In order to add another DataFrame or Series to an existing HDF file
         please use append mode and a different a key.
 
-        For more information see the :ref:`user guide <io.html#io-hdf5>`.
+        For more information see the :ref:`user guide <io.hdf5>`.
 
         Parameters
         ----------
@@ -1929,8 +1929,7 @@ def to_hdf(self, path_or_buf, key, **kwargs):
         data_columns :  list of columns or True, optional
             List of columns to create as indexed data columns for on-disk
             queries, or True to use all columns. By default only the axes
-            of the object are indexed. See `here
-            <http://pandas.pydata.org/pandas-docs/stable/io.html#query-via-data-columns>`__.
+            of the object are indexed. See :ref:`io.hdf5-query-data-columns`.
             Applicable only to format='table'.
         complevel : {0-9}, optional
             Specifies a compression level for data.
@@ -2141,7 +2140,7 @@ def to_pickle(self, path, compression='infer',
             .. versionadded:: 0.20.0
         protocol : int
             Int which indicates which protocol should be used by the pickler,
-            default HIGHEST_PROTOCOL (see [1], paragraph 12.1.2). The possible
+            default HIGHEST_PROTOCOL (see [1]_ paragraph 12.1.2). The possible
             values for this parameter depend on the version of Python. For
             Python 2.x, possible values are 0, 1, 2. For Python>=3.0, 3 is a
             valid value. For Python >= 3.4, 4 is a valid value. A negative
diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -467,8 +467,8 @@ def asobject(self):
         """Return object Series which contains boxed values.
 
         .. deprecated :: 0.23.0
-            Use ``astype(object) instead.
 
+           Use ``astype(object) instead.
 
         *this is an internal non-public method*
         """
@@ -1772,18 +1772,20 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs):
         return self.index[i]
 
     # ndarray compat
-    argmin = deprecate('argmin', idxmin, '0.21.0',
-                       msg="'argmin' is deprecated, use 'idxmin' instead. "
-                           "The behavior of 'argmin' will be corrected to "
-                           "return the positional minimum in the future. "
-                           "Use 'series.values.argmin' to get the position of "
-                           "the minimum now.")
-    argmax = deprecate('argmax', idxmax, '0.21.0',
-                       msg="'argmax' is deprecated, use 'idxmax' instead. "
-                           "The behavior of 'argmax' will be corrected to "
-                           "return the positional maximum in the future. "
-                           "Use 'series.values.argmax' to get the position of "
-                           "the maximum now.")
+    argmin = deprecate(
+        'argmin', idxmin, '0.21.0',
+        msg=dedent("""\
+        'argmin' is deprecated, use 'idxmin' instead. The behavior of 'argmin'
+        will be corrected to return the positional minimum in the future.
+        Use 'series.values.argmin' to get the position of the minimum now.""")
+    )
+    argmax = deprecate(
+        'argmax', idxmax, '0.21.0',
+        msg=dedent("""\
+        'argmax' is deprecated, use 'idxmax' instead. The behavior of 'argmax'
+        will be corrected to return the positional maximum in the future.
+        Use 'series.values.argmax' to get the position of the maximum now.""")
+    )
 
     def round(self, decimals=0, *args, **kwargs):
         """
diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py
@@ -3100,7 +3100,7 @@ def hist(self, by=None, bins=10, **kwds):
 
         A histogram is a representation of the distribution of data.
         This function groups the values of all given Series in the DataFrame
-        into bins, and draws all bins in only one :ref:`matplotlib.axes.Axes`.
+        into bins and draws all bins in one :class:`matplotlib.axes.Axes`.
         This is useful when the DataFrame's Series are in a similar scale.
 
         Parameters
diff --git a/pandas/util/_decorators.py b/pandas/util/_decorators.py
@@ -45,13 +45,18 @@ def wrapper(*args, **kwargs):
         return alternative(*args, **kwargs)
 
     # adding deprecated directive to the docstring
-    msg = msg or 'Use `{alt_name}` instead.'
-    docstring = '.. deprecated:: {}\n'.format(version)
-    docstring += dedent('    ' + ('\n'.join(wrap(msg, 70))))
-
-    if getattr(wrapper, '__doc__') is not None:
-        docstring += dedent(wrapper.__doc__)
-
+    msg = msg or 'Use `{alt_name}` instead.'.format(alt_name=alt_name)
+    tpl = dedent("""
+    .. deprecated:: {version}
+
+       {msg}
+
+    {rest}
+    """)
+    rest = getattr(wrapper, '__doc__', '')
+    docstring = tpl.format(version=version,
+                           msg='\n    '.join(wrap(msg, 70)),
+                           rest=dedent(rest))
     wrapper.__doc__ = docstring
 
     return wrapper
