DOC: update DataFrame.to_records
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
# paste output of "scripts/validate_docstrings.py <your-function-or-method>" here
# between the "```" (remove this comment, but keep the "```")

################################################################################
################### Docstring (pandas.DataFrame.to_records)  ###################
################################################################################

Convert DataFrame to 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.
convert_datetime64 : boolean, default True
    Whether to convert the index to datetime.datetime if it is a
    DatetimeIndex.

Returns
-------
y : 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 (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')])

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.to_records" correct. :)

```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

- [ ] closes #xxxx
- [ ] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs
name: IO Data
description: IO issues that don't fit into a more specific label
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
@TomAugspurger Thanks for the review, have addressed all your comments. The doctests now pass and the validate script is still happy. 
By the way big fan of your blog, learned lots from it especially about multi-index/columns. Don't miss an occasion to recommend it to others. Keep it up!!

Thanks @samuelsinayoko!