DOC: add comment about JULIAN_OFFSET

jklymak · jklymak · commit cec46b53c45d · 2020-07-22T16:19:38.000-07:00
diff --git a/doc/api/next_api_changes/deprecations/17983-JMK.rst b/doc/api/next_api_changes/deprecations/17983-JMK.rst
@@ -6,11 +6,11 @@ an accurate Matplotlib datenum relative to the new Matplotlib epoch
 handling (`~.dates.get_epoch` and :rc:`date.epoch`).  This version
 reverts the deprecation.
 
-`~.dates.epoch2num`, `~.dates.julian2num` use :rc:`date.epoch`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Functions `~.dates.epoch2num` and  ``julian2num`` use :rc:`date.epoch`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now `~.dates.epoch2num` and `~.dates.julian2num` return floating point
+Now `~.dates.epoch2num` and (undocumented) ``julian2num`` return floating point
 days since `~.dates.get_epoch` as set by :rc:`date.epoch`, instead of
 floating point days since the old epoch of "0000-12-31T00:00:00".  If
 needed, you can translate from the new to old values as
-`old = new + mdates.date2num(np.datetime64('0000-12-31'))`
+``old = new + mdates.date2num(np.datetime64('0000-12-31'))``
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -197,7 +197,13 @@ def _get_rc_timezone():
 Time-related constants.
 """
 EPOCH_OFFSET = float(datetime.datetime(1970, 1, 1).toordinal())
-JULIAN_OFFSET = 1721424.5                         # Julian date at 0001-01-01
+# EPOCH_OFFSET is not used by matplotlib
+JULIAN_OFFSET = 1721424.5  # Julian date at 0000-12-31
+# note that the Julian day epoch is achievable w/
+# np.datetime64('-4713-11-24T12:00:00'); datetime64 is proleptic
+# Gregorian and BC has a one-year offset.  So
+# np.datetime64('0000-12-31') - np.datetime64('-4713-11-24T12:00') = 1721424.5
+# Ref: https://en.wikipedia.org/wiki/Julian_day
 MICROSECONDLY = SECONDLY + 1
 HOURS_PER_DAY = 24.
 MIN_PER_HOUR = 60.
@@ -445,7 +451,8 @@ def julian2num(j):
     Parameters
     ----------
     j : float or sequence of floats
-        Julian date(s) (days relative to 4713 BC Jan 1, 12:00:00)
+        Julian date(s) (days relative to 4713 BC Jan 1, 12:00:00 Julian
+        calendar or 4714 BC Nov 24, 12:00:00, proleptic Gregorian calendar)
 
     Returns
     -------
diff --git a/setup.cfg.template b/setup.cfg.template
@@ -5,7 +5,7 @@
 [libs]
 # By default, Matplotlib builds with LTO, which may be slow if you re-compile
 # often, and don't need the space saving/speedup.
-#enable_lto = True
+enable_lto = False
 # By default, Matplotlib downloads and builds its own copy of FreeType, and
 # builds its own copy of Qhull.  You may set the following to True to instead
 # link against a system FreeType/Qhull.
@@ -18,6 +18,7 @@
 # image files) are installed by default, but that can be changed here.
 #tests = False
 #sample_data = True
+tests = True
 
 [gui_support]
 # Matplotlib supports multiple GUI toolkits, known as backends.
