Repository: numpy/numpy
Pull request: DOC: Improve datetime64 docs.
<!--         ----------------------------------------------------------------
                MAKE SURE YOUR PR GETS THE ATTENTION IT DESERVES!
                ----------------------------------------------------------------

*  FORMAT IT RIGHT:
      http://www.numpy.org/devdocs/dev/development_workflow.html#writing-the-commit-message

*  IF IT'S A NEW FEATURE OR API CHANGE, TEST THE WATERS:
      http://www.numpy.org/devdocs/dev/development_workflow.html#get-the-mailing-list-s-opinion

*  HIT ALL THE GUIDELINES:
      https://numpy.org/devdocs/dev/index.html#guidelines

*  WHAT TO DO IF WE HAVEN'T GOTTEN BACK TO YOU:
      http://www.numpy.org/devdocs/dev/development_workflow.html#getting-your-pr-reviewed
-->

Adding clarification to datetime64. Resolves #14299

Problem statement:
DOC: Improve datetime64 docs?
- List the inputs forms accepted by the constructor: Right now I think only construction from a string is mentioned; construction from a numeric offset relative to the Unix epoch (a common case, I would think) isn't.  Note that this leads to the small footgun
```
In [1]: np.datetime64(1, 'Y')
Out[1]: numpy.datetime64('1971')

In [2]: np.datetime64('1', 'Y')
Out[2]: numpy.datetime64('0001')
```
which certainly makes sense (given how other units work) but may be worth mentioning as well.

- Note on experimentalness of the API: there's still a note at the top saying "The datetime API is experimental in 1.7.0, and may undergo changes in future versions of NumPy."  Numpy 1.7 is `np.timedelta64(6.5, 'Y')` old now; is this note still true?

- Deemphasize behavior on old versions of numpy: Right now ~30% of the page is about changes in behavior that occurred in numpy 1.7 and in numpy 1.11, which are certainly important for migrating old code but of little interest for many users.  Maybe these could be deemphasized somehow, or the examples shortened?

Hints from issue discussion:
Closed by gh-14475.  Please reopen if there are points here the new documentation does not address.
Thanks, but AFAICS it remains not mentioned that datetime64 can be constructed from ints (the PR only mentions timedelta64), and the note on experimentalness is still there.
I would like to take this one

Commit message: DOC: Improve datetime64 docs #14299

Patch to review:
diff --git a/doc/source/reference/arrays.datetime.rst b/doc/source/reference/arrays.datetime.rst
index c5947620efe7..fcdb9d934d82 100644
--- a/doc/source/reference/arrays.datetime.rst
+++ b/doc/source/reference/arrays.datetime.rst
@@ -20,9 +20,9 @@ Basic Datetimes
 ===============
 
 The most basic way to create datetimes is from strings in
-ISO 8601 date or datetime format. The unit for internal storage
-is automatically selected from the form of the string, and can
-be either a :ref:`date unit <arrays.dtypes.dateunits>` or a
+ISO 8601 date, datetime format or from integer to UNIX time. 
+The unit for internal storage is automatically selected from the 
+form of the string, and can be either a :ref:`date unit <arrays.dtypes.dateunits>` or a
 :ref:`time unit <arrays.dtypes.timeunits>`. The date units are years ('Y'),
 months ('M'), weeks ('W'), and days ('D'), while the time units are
 hours ('h'), minutes ('m'), seconds ('s'), milliseconds ('ms'), and
@@ -36,6 +36,11 @@ letters, for a "Not A Time" value.
 
     >>> np.datetime64('2005-02-25')
     numpy.datetime64('2005-02-25')
+    
+    UNIX time, by providing integer and a date unit :
+
+    >>> np.datetime64(1, 'Y')
+    numpy.datetime64('1971')   
 
     Using months for the unit:
 


Code review comments:
diff_hunk: @@ -36,6 +36,11 @@ letters, for a "Not A Time" value.
 
     >>> np.datetime64('2005-02-25')
     numpy.datetime64('2005-02-25')
+    
+    UNIX time, by providing integer and a date unit :
path: doc/source/reference/arrays.datetime.rst
text: @user1:
UNIX isn't related to "time", only to "epoch". So how about:

_From an integer and a date unit, here 1 year since the UNIX epoch:_