From 98916fa4dcee82eb29fec36f6a4ed98de04469af Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Tue, 27 Mar 2018 16:28:51 -0500 Subject: [PATCH 1/7] DOC: Fix various warnings --- doc/source/comparison_with_r.rst | 2 +- doc/source/cookbook.rst | 2 ++ doc/source/io.rst | 2 ++ doc/source/release.rst | 2 +- doc/source/whatsnew/v0.10.0.txt | 2 +- doc/source/whatsnew/v0.16.1.txt | 2 +- doc/source/whatsnew/v0.23.0.txt | 2 +- doc/source/whatsnew/v0.6.1.txt | 4 ++-- pandas/core/generic.py | 3 +-- pandas/plotting/_core.py | 2 +- 10 files changed, 13 insertions(+), 10 deletions(-) diff --git a/doc/source/comparison_with_r.rst b/doc/source/comparison_with_r.rst index eb97aeeb7e696..a7586f623a160 100644 --- 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 `. +documentation `. |meltdf|_ ~~~~~~~~~~~~~~~~ diff --git a/doc/source/cookbook.rst b/doc/source/cookbook.rst index b6690eff89836..4e61228d5c0ad 100644 --- a/doc/source/cookbook.rst +++ b/doc/source/cookbook.rst @@ -411,6 +411,8 @@ Levels `Flatten Hierarchical columns `__ +.. _cookbook.missing_data: + Missing Data ------------ diff --git a/doc/source/io.rst b/doc/source/io.rst index d6bd81861adee..68b431925d983 100644 --- a/doc/source/io.rst +++ b/doc/source/io.rst @@ -3862,6 +3862,8 @@ Then create the index when finished appending. See `here `__ 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 index 8e063116cbf07..da3362b47b29b 100644 --- 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 `. + with matplotlib. See :ref:`here `. - Improvements to the Parquet IO functions introduced in 0.21.0. See :ref:`here `. diff --git a/doc/source/whatsnew/v0.10.0.txt b/doc/source/whatsnew/v0.10.0.txt index 222a2da23865c..e43ece6685c4a 100644 --- 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 ` for NDim. Here is a taste of what to expect. +`Docs` for NDim. 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 index 9e1dc391d7ace..15fe8e9c21b94 100644 --- 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 ` (:issue:`8961`) + In pandas 0.17.0, the sub-package ``pandas.io.data`` will be removed in favor of a separately installable package. See `here for details` (:issue:`8961`) Enhancements ~~~~~~~~~~~~ diff --git a/doc/source/whatsnew/v0.23.0.txt b/doc/source/whatsnew/v0.23.0.txt index d7c92ed822ffc..b9e86479f60ba 100644 --- 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 ` for more (:issue:`14781`). + :ref:`Registering Custom 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 index a2dab738546f9..acd5b0774f2bb 100644 --- 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 ` and an :ref:`axis option ` (:issue:`461`) -- Implement new :ref:`SparseArray ` and :ref:`SparseList ` +- Implement new :ref:`SparseArray ` and `SparseList` data structures. SparseSeries now derives from SparseArray (:issue:`463`) - :ref:`Better console printing options ` (:issue:`453`) - Implement fast :ref:`data ranking ` for Series and DataFrame, fast versions of scipy.stats.rankdata (:issue:`428`) -- Implement :ref:`DataFrame.from_items ` alternate +- Implement `DataFrame.from_items` alternate constructor (:issue:`444`) - DataFrame.convert_objects method for :ref:`inferring better dtypes ` for object columns (:issue:`302`) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 80885fd9ef139..484f4427c2396 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -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 - `__. + 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. diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 89e04f03cda32..6c3d07124215b 100644 --- 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 From 6070e08a29ae55fd340b4c70f6da523f5c9762c3 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 28 Mar 2018 09:37:57 -0500 Subject: [PATCH 2/7] DOC: deprecate formatting --- pandas/core/series.py | 28 +++++++++++++++------------- pandas/util/_decorators.py | 19 ++++++++++++------- 2 files changed, 27 insertions(+), 20 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 62f0ea3ce8b2a..d066e9409b594 100644 --- 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/util/_decorators.py b/pandas/util/_decorators.py index 1753bc8b8fc33..624fbbbd4f05e 100644 --- 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 From 319aedbdecf9c2d00cd40e565fb0656cb623f7c3 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 28 Mar 2018 09:41:41 -0500 Subject: [PATCH 3/7] images pickle reference --- doc/source/whatsnew/v0.7.3.txt | 6 +++--- pandas/core/generic.py | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/whatsnew/v0.7.3.txt b/doc/source/whatsnew/v0.7.3.txt index 6b5199c55cbf5..77cc72d8707cf 100644 --- 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 ` to diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 1b139b9efef0d..89ee4a0ab6fe3 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2140,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 From a0254ceb1a21722cdc1c97133711cd3023aaac4a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 28 Mar 2018 11:05:38 -0500 Subject: [PATCH 4/7] More docs --- doc/source/whatsnew/v0.10.0.txt | 2 +- doc/source/whatsnew/v0.16.1.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/whatsnew/v0.10.0.txt b/doc/source/whatsnew/v0.10.0.txt index e43ece6685c4a..3fc05158b7fe7 100644 --- 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. -`Docs` 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 index 15fe8e9c21b94..5c716f6ad45c1 100644 --- 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 `here for details` (: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 ~~~~~~~~~~~~ From acbe50af67d7e1d0b5ca17829b4d2eede86dcb42 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 28 Mar 2018 13:20:34 -0500 Subject: [PATCH 5/7] DOC: A couple more --- doc/source/contributing.rst | 13 +++++++++---- pandas/core/generic.py | 2 +- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 967d1fe3369f0..1c2329c3df84a 100644 --- 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 ` 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 `_ 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,7 +1025,7 @@ 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: @@ -1028,7 +1033,7 @@ 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/pandas/core/generic.py b/pandas/core/generic.py index 89ee4a0ab6fe3..d5cd22732f0a9 100644 --- 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 `. + For more information see the :ref:`user guide `. Parameters ---------- From c68f2a2ce6f9789d92f784486690bc653063981e Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 28 Mar 2018 13:23:11 -0500 Subject: [PATCH 6/7] Escaping --- doc/source/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 1c2329c3df84a..f977cbd1a2894 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -905,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 From d6eaf5f11f51bb867f408c0bb1b0b3740265cd4a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 28 Mar 2018 13:26:24 -0500 Subject: [PATCH 7/7] Fix escaping again --- doc/source/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index f977cbd1a2894..6d5ac31c39a62 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -905,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