Merge pull request #10589 from bashtage/convert-objects-doc-fix

DOC: Small improvement to convert_objects doc

Author: jorisvandenbossche

doc/source/basics.rst

@@ -1528,12 +1528,14 @@ object conversion
     :ref:`API changes <whatsnew_0170.api_breaking.convert_objects>`
     for more details.
 
-:meth:`~DataFrame.convert_objects` is a method to try to force conversion of
-types from the ``object`` dtype to other types. To try converting specific
-types that are *number like*, e.g. could be a string that represents a number,
-pass ``numeric=True``. To force the conversion, add the keyword argument
-``coerce=True``.  This will force strings and number-like objects to be numbers if
-possible, otherwise they will be set to ``np.nan``.
+:meth:`~DataFrame.convert_objects` is a method that converts columns from
+the ``object`` dtype to datetimes, timedeltas or floats. For example, to
+attempt conversion of object data that are *number like*, e.g. could be a
+string that represents a number, pass ``numeric=True``. By default, this will
+attempt a soft conversion and so will only succeed if the entire column is
+convertible. To force the conversion, add the keyword argument ``coerce=True``.
+This will force strings and number-like objects to be numbers if
+possible, and other values will be set to ``np.nan``.
 
 .. ipython:: python
 
@@ -1549,7 +1551,7 @@ possible, otherwise they will be set to ``np.nan``.
 To force conversion to ``datetime64[ns]``, pass ``datetime=True`` and ``coerce=True``.
 This will convert any datetime-like object to dates, forcing other values to ``NaT``.
 This might be useful if you are reading in data which is mostly dates,
-but occasionally has non-dates intermixed and you want to represent as missing.
+but occasionally contains non-dates that you wish to represent as missing.
 
 .. ipython:: python
 

doc/source/whatsnew/v0.17.0.txt

@@ -80,16 +80,16 @@ Other enhancements
 
 .. _whatsnew_0170.api:
 
-Backwards incompatible API changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 .. _whatsnew_0170.api_breaking:
 
-.. _whatsnew_0170.api_breaking.other:
+Backwards incompatible API changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. _whatsnew_0170.api_breaking.convert_objects:
 Changes to convert_objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _whatsnew_0170.api_breaking.convert_objects:
+
 - ``DataFrame.convert_objects`` keyword arguments have been shortened. (:issue:`10265`)
 
 =====================   =============
@@ -101,8 +101,8 @@ Old                     New
 =====================   =============
 
 - Coercing types with ``DataFrame.convert_objects`` is now implemented using the
-keyword argument ``coerce=True``.  Previously types were coerced by setting a
-keyword argument to ``'coerce'`` instead of ``True``, as in ``convert_dates='coerce'``.
+  keyword argument ``coerce=True``.  Previously types were coerced by setting a
+  keyword argument to ``'coerce'`` instead of ``True``, as in ``convert_dates='coerce'``.
 
   .. ipython:: python
 
@@ -125,7 +125,7 @@ keyword argument to ``'coerce'`` instead of ``True``, as in ``convert_dates='coe
     df.convert_objects(numeric=True, coerce=True)
 
 - In earlier versions of pandas, ``DataFrame.convert_objects`` would not coerce
-numeric types when there were no values convertible to a numeric type.  For example,
+  numeric types when there were no values convertible to a numeric type.  For example,
 
   .. code-block:: python
 
@@ -136,21 +136,22 @@ numeric types when there were no values convertible to a numeric type.  For exam
      0  a
      1  b
 
-returns the original DataFrame with no conversion. This change alters
-this behavior so that
+  returns the original DataFrame with no conversion. This change alters
+  this behavior so that
 
   .. ipython:: python
 
     pd.DataFrame({'s': ['a','b']})
     df.convert_objects(numeric=True, coerce=True)
 
-converts all non-number-like strings to ``NaN``.
+  converts all non-number-like strings to ``NaN``.
 
 - In earlier versions of pandas, the default behavior was to try and convert
-datetimes and timestamps. The new default is for ``DataFrame.convert_objects``
-to do nothing, and so it is necessary to pass at least one conversion target
-in the method call.
+  datetimes and timestamps. The new default is for ``DataFrame.convert_objects``
+  to do nothing, and so it is necessary to pass at least one conversion target
+  in the method call.
 
+.. _whatsnew_0170.api_breaking.other:
 
 Other API Changes
 ^^^^^^^^^^^^^^^^^