DOC: Extension whatsenw (pandas-dev#20533)

DOC: various warnings.

Author: TomAugspurger

ci/build_docs.sh

@@ -24,6 +24,7 @@ if [ "$DOC" ]; then
     source activate pandas
 
     mv "$TRAVIS_BUILD_DIR"/doc /tmp
+    mv "$TRAVIS_BUILD_DIR/LICENSE" /tmp  # included in the docs.
     cd /tmp/doc
 
     echo ###############################

doc/source/api.rst

@@ -2576,4 +2576,3 @@ objects.
    generated/pandas.Series.ix
    generated/pandas.Series.imag
    generated/pandas.Series.real
-   generated/pandas.Timestamp.offset

doc/source/io.rst

@@ -2263,7 +2263,7 @@ round-trippable manner.
    new_df.dtypes
 
 Please note that the literal string 'index' as the name of an :class:`Index`
-is not round-trippable, nor are any names beginning with 'level_' within a
+is not round-trippable, nor are any names beginning with ``'level_'`` within a
 :class:`MultiIndex`. These are used by default in :func:`DataFrame.to_json` to
 indicate missing values and the subsequent read cannot distinguish the intent.
 

doc/source/timeseries.rst

@@ -198,8 +198,9 @@ This could also potentially speed up the conversion considerably.
     pd.to_datetime('12-11-2010 00:00', format='%d-%m-%Y %H:%M')
 
 For more information on the choices available when specifying the ``format`` 
-option, see the Python `datetime documentation 
-<https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior`__.
+option, see the Python `datetime documentation`_.
+
+.. _datetime documentation: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior
 
 Assembling Datetime from Multiple DataFrame Columns
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/source/whatsnew/v0.23.0.txt

@@ -299,6 +299,63 @@ Supplying a ``CategoricalDtype`` will make the categories in each column consist
     df['A'].dtype
     df['B'].dtype
 
+.. _whatsnew_023.enhancements.extension:
+
+Extending Pandas with Custom Types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pandas now supports storing array-like objects that aren't necessarily 1-D NumPy
+arrays as columns in a DataFrame or values in a Series. This allows third-party
+libraries to implement extensions to NumPy's types, similar to how pandas
+implemented categoricals, datetimes with timezones, periods, and intervals.
+
+As a demonstration, we'll use cyberpandas_, which provides an ``IPArray`` type
+for storing ip addresses.
+
+.. code-block:: ipython
+
+   In [1]: from cyberpandas import IPArray
+
+   In [2]: values = IPArray([
+      ...:     0,
+      ...:     3232235777,
+      ...:     42540766452641154071740215577757643572
+      ...: ])
+      ...:
+      ...:
+
+``IPArray`` isn't a normal 1-D NumPy array, but because it's a pandas
+``ExtensionArray``, it can be stored properly inside pandas' containers.
+
+.. code-block:: ipython
+
+   In [3]: ser = pd.Series(values)
+      ...:
+
+   In [4]: ser
+   Out[4]:
+   0                         0.0.0.0
+   1                     192.168.1.1
+   2    2001:db8:85a3::8a2e:370:7334
+   dtype: ip
+
+Notice that the dtype is ``ip``. The missing value semantics of the underlying
+array are respected:
+
+   In [5]: ser.isna()
+      ...:
+   Out[5]:
+   0     True
+   1    False
+   2    False
+   dtype: bool
+
+For more, see the :ref:`extension types <extending.extension-types>`
+documentation. If you build an extension array, publicize it on our
+:ref:`ecosystem page <ecosystem.extensions>`.
+
+.. _cyberpandas: https://cyberpandas.readthedocs.io/en/latest/
+
 .. _whatsnew_0230.enhancements.other:
 
 Other Enhancements

pandas/core/series.py

@@ -468,7 +468,7 @@ def asobject(self):
 
         .. deprecated :: 0.23.0
 
-           Use ``astype(object) instead.
+           Use ``astype(object)`` instead.
 
         *this is an internal non-public method*
         """