DOC: Added an example of pitfalls when using astype

 - [x] closes #13260    - [ ] tests added / passed   - [ ] passes
``git diff upstream/master | flake8 --diff``   - [ ] whatsnew entry

Author: Amol <[email protected]>

Closes #13278 from pfrcks/bug13260 and squashes the following commits:

035a177 [Amol] DOC: Final touches
c30209d [Amol] DOC: Cleaning up
278e922 [Amol] DOC: Some cleaning up
e1877bf [Amol] DOC: Restructured the documentation
f394045 [Amol] DOC: Cleaned up the documentation
705e1a5 [Amol] DOC: Added an example of pitfalls when using astype

Author: pfrcks

doc/source/basics.rst

@@ -1726,6 +1726,28 @@ then the more *general* one will be used as the result of the operation.
    # conversion of dtypes
    df3.astype('float32').dtypes
 
+Convert a subset of columns to a specified type using :meth:`~DataFrame.astype`
+
+.. ipython:: python
+
+   dft = pd.DataFrame({'a': [1,2,3], 'b': [4,5,6], 'c': [7, 8, 9]})
+   dft[['a','b']] = dft[['a','b']].astype(np.uint8)
+   dft
+   dft.dtypes
+
+.. note::
+
+    When trying to convert a subset of columns to a specified type using :meth:`~DataFrame.astype`  and :meth:`~DataFrame.loc`, upcasting occurs.
+
+    :meth:`~DataFrame.loc` tries to fit in what we are assigning to the current dtypes, while ``[]`` will overwrite them taking the dtype from the right hand side. Therefore the following piece of code produces the unintended result.
+
+    .. ipython:: python
+
+       dft = pd.DataFrame({'a': [1,2,3], 'b': [4,5,6], 'c': [7, 8, 9]})
+       dft.loc[:, ['a', 'b']].astype(np.uint8).dtypes
+       dft.loc[:, ['a', 'b']] = dft.loc[:, ['a', 'b']].astype(np.uint8)
+       dft.dtypes
+
 object conversion
 ~~~~~~~~~~~~~~~~~