Merge pull request #10348 from jorisvandenbossche/docstrings

DOC: fix docstrings

Author: jorisvandenbossche

doc/source/release.rst

@@ -53,6 +53,11 @@ pandas 0.16.2
 This is a minor release from 0.16.1 and includes a large number of bug fixes
 along with several new features, enhancements, and performance improvements.
 
+Highlights include:
+
+- A new ``pipe`` method, see :ref:`here <whatsnew_0162.enhancements.pipe>`
+- Documentation on how to use `numba <http://numba.pydata.org>`_ with *pandas*, see :ref:`here <enhancingperf.numba>`
+
 See the :ref:`v0.16.2 Whatsnew <whatsnew_0162>` overview for an extensive list
 of all enhancements and bugs that have been fixed in 0.16.2.
 

doc/source/whatsnew/v0.16.2.txt

@@ -13,7 +13,6 @@ Highlights include:
 - A new ``pipe`` method, see :ref:`here <whatsnew_0162.enhancements.pipe>`
 - Documentation on how to use numba_ with *pandas*, see :ref:`here <enhancingperf.numba>`
 
-Check the :ref:`API Changes <whatsnew_0162.api>` before updating.
 
 .. contents:: What's new in v0.16.2
     :local:

pandas/core/generic.py

@@ -2050,7 +2050,7 @@ def sample(self, n=None, frac=None, replace=False, weights=None, random_state=No
         return self.take(locs, axis=axis)
 
     _shared_docs['pipe'] = ("""
-        Apply func(self, *args, **kwargs)
+        Apply func(self, \*args, \*\*kwargs)
 
         .. versionadded:: 0.16.2
 

pandas/io/json.py

@@ -640,34 +640,39 @@ def json_normalize(data, record_path=None, meta=None,
         path to records is ['foo', 'bar']
     meta_prefix : string, default None
 
+    Returns
+    -------
+    frame : DataFrame
+
     Examples
     --------
-    data = [{'state': 'Florida',
-             'shortname': 'FL',
-             'info': {
-                  'governor': 'Rick Scott'
-             },
-             'counties': [{'name': 'Dade', 'population': 12345},
-                         {'name': 'Broward', 'population': 40000},
-                         {'name': 'Palm Beach', 'population': 60000}]},
-            {'state': 'Ohio',
-             'shortname': 'OH',
-             'info': {
-                  'governor': 'John Kasich'
-             },
-             'counties': [{'name': 'Summit', 'population': 1234},
-                          {'name': 'Cuyahoga', 'population': 1337}]}]
-
-    result = json_normalize(data, 'counties', ['state', 'shortname',
-                                              ['info', 'governor']])
-
-      state    governor
-    Florida  Rick Scott
 
+    >>> data = [{'state': 'Florida',
+    ...          'shortname': 'FL',
+    ...          'info': {
+    ...               'governor': 'Rick Scott'
+    ...          },
+    ...          'counties': [{'name': 'Dade', 'population': 12345},
+    ...                      {'name': 'Broward', 'population': 40000},
+    ...                      {'name': 'Palm Beach', 'population': 60000}]},
+    ...         {'state': 'Ohio',
+    ...          'shortname': 'OH',
+    ...          'info': {
+    ...               'governor': 'John Kasich'
+    ...          },
+    ...          'counties': [{'name': 'Summit', 'population': 1234},
+    ...                       {'name': 'Cuyahoga', 'population': 1337}]}]
+    >>> from pandas.io.json import json_normalize
+    >>> result = json_normalize(data, 'counties', ['state', 'shortname',
+    ...                                           ['info', 'governor']])
+    >>> result
+             name  population info.governor    state shortname
+    0        Dade       12345    Rick Scott  Florida        FL
+    1     Broward       40000    Rick Scott  Florida        FL
+    2  Palm Beach       60000    Rick Scott  Florida        FL
+    3      Summit        1234   John Kasich     Ohio        OH
+    4    Cuyahoga        1337   John Kasich     Ohio        OH
 
-    Returns
-    -------
-    frame : DataFrame
     """
     def _pull_field(js, spec):
         result = js