From 6d7272a7e1b129b294e8dc84f847da00c567612f Mon Sep 17 00:00:00 2001
From: Samuel Sinayoko <samuelsinayoko@bmlltech.com>
Date: Sun, 11 Mar 2018 11:58:09 +0000
Subject: [PATCH] DOC: update DataFrame.to_records (#20191)

* Update to_records docstring.

- Minor changes (missing dots, newlines) to make tests pass.
- More examples.

* Fix html docs.

Missing newlines.

* Reword datetime type information.

* flake8 errors

* Fix typo (duplicated type)

* Remove unwanted blank line after Examples.

* Fix doctests.

```
(pandas_dev) sinayoks@landade:~/dev/pandas/ $ pytest --doctest-modules pandas/core/frame.py -k to_record
========================================================================================== test session starts ==========================================================================================
platform darwin -- Python 3.6.4, pytest-3.4.2, py-1.5.2, pluggy-0.6.0
rootdir: /Users/sinayoks/dev/pandas, inifile: setup.cfg
plugins: xdist-1.22.1, forked-0.2, cov-2.5.1
collected 43 items

pandas/core/frame.py .                                                                                                                                                                            [100%]

========================================================================================== 42 tests deselected ==========================================================================================
```

* Few more changes
---
 pandas/core/frame.py | 58 ++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 53 insertions(+), 5 deletions(-)

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index d8269b605eef9..0f94b75a37a74 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -1209,20 +1209,68 @@ def from_records(cls, data, index=None, exclude=None, columns=None,
 
     def to_records(self, index=True, convert_datetime64=True):
         """
-        Convert DataFrame to record array. Index will be put in the
-        'index' field of the record array if requested
+        Convert DataFrame to a NumPy record array.
+
+        Index will be put in the 'index' field of the record array if
+        requested.
 
         Parameters
         ----------
         index : boolean, default True
-            Include index in resulting record array, stored in 'index' field
+            Include index in resulting record array, stored in 'index' field.
         convert_datetime64 : boolean, default True
             Whether to convert the index to datetime.datetime if it is a
-            DatetimeIndex
+            DatetimeIndex.
 
         Returns
         -------
-        y : recarray
+        y : numpy.recarray
+
+        See Also
+        --------
+        DataFrame.from_records: convert structured or record ndarray
+            to DataFrame.
+        numpy.recarray: ndarray that allows field access using
+            attributes, analogous to typed columns in a
+            spreadsheet.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2], 'B': [0.5, 0.75]},
+        ...                   index=['a', 'b'])
+        >>> df
+           A     B
+        a  1  0.50
+        b  2  0.75
+        >>> df.to_records()
+        rec.array([('a', 1, 0.5 ), ('b', 2, 0.75)],
+                  dtype=[('index', 'O'), ('A', '<i8'), ('B', '<f8')])
+
+        The index can be excluded from the record array:
+
+        >>> df.to_records(index=False)
+        rec.array([(1, 0.5 ), (2, 0.75)],
+                  dtype=[('A', '<i8'), ('B', '<f8')])
+
+        By default, timestamps are converted to `datetime.datetime`:
+
+        >>> df.index = pd.date_range('2018-01-01 09:00', periods=2, freq='min')
+        >>> df
+                             A     B
+        2018-01-01 09:00:00  1  0.50
+        2018-01-01 09:01:00  2  0.75
+        >>> df.to_records()
+        rec.array([(datetime.datetime(2018, 1, 1, 9, 0), 1, 0.5 ),
+                   (datetime.datetime(2018, 1, 1, 9, 1), 2, 0.75)],
+                  dtype=[('index', 'O'), ('A', '<i8'), ('B', '<f8')])
+
+        The timestamp conversion can be disabled so NumPy's datetime64
+        data type is used instead:
+
+        >>> df.to_records(convert_datetime64=False)
+        rec.array([('2018-01-01T09:00:00.000000000', 1, 0.5 ),
+                   ('2018-01-01T09:01:00.000000000', 2, 0.75)],
+                  dtype=[('index', '<M8[ns]'), ('A', '<i8'), ('B', '<f8')])
         """
         if index:
             if is_datetime64_any_dtype(self.index) and convert_datetime64: