From fc1db62c117e445b24f1536a9732fabacbb3554e Mon Sep 17 00:00:00 2001
From: Brandon Rhodes <brandon@rhodesmill.org>
Date: Sun, 25 Feb 2024 12:59:16 -0500
Subject: [PATCH] Show how to print out leap second table

---
 CHANGELOG.rst                                 |  4 +-
 .../documentation/accuracy-efficiency.rst     | 44 ++++++++++++++++++-
 skyfield/documentation/time.rst               |  3 ++
 skyfield/positionlib.py                       |  2 +-
 4 files changed, 48 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 1bc0dc3fd..797fe6cd7 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -301,7 +301,7 @@ v1.35 — 2020 December 31
   (The old method will remain in place to support legacy code,
   but is discouraged in new applications.)
 
-* The effects of :ref:`Polar motion` — if configured — are now included
+* The effects of :ref:`polar-motion` — if configured — are now included
   both when computing the position in space of an Earth latitude and longitude,
   and when determining the latitude and longitude beneath a celestial position.
 
@@ -329,7 +329,7 @@ v1.34 — 2020 December 10
 
 * Added an official :class:`~skyfield.framelib.itrs` reference frame.
 
-* Added support for IERS :ref:`polar motion` 𝑥 and 𝑦.
+* Added support for IERS :ref:`polar-motion` 𝑥 and 𝑦.
 
 * Added a method :meth:`~skyfield.toposlib.GeographicPosition.lst_hours_at()`
   that computes Local Sidereal Time.
diff --git a/skyfield/documentation/accuracy-efficiency.rst b/skyfield/documentation/accuracy-efficiency.rst
index 805edfda3..c52485c34 100644
--- a/skyfield/documentation/accuracy-efficiency.rst
+++ b/skyfield/documentation/accuracy-efficiency.rst
@@ -7,8 +7,6 @@ This document is a work in progress,
 that will be expanded into a full guide.
 Right now it covers only one topic.
 
-.. _polar motion:
-
 -----------------------
 Precession and Nutation
 -----------------------
@@ -41,6 +39,8 @@ into the Earth equatorial coordinate system of that date and time.
 See the section on :ref:`Coordinates:Rotation Matrices`
 for a guide to using a rotation matrix.
 
+.. _polar-motion:
+
 ------------
 Polar Motion
 ------------
@@ -108,6 +108,46 @@ simply install the IERS tables on your timescale object
 as shown in the example code above.
 Polar motion will be used everywhere that it applies.
 
+.. _the-leap-second-table:
+
+---------------------
+The leap second table
+---------------------
+
+If you want to double-check that Skyfield’s leap second table
+agrees with other tools or software,
+you can easily print it out.
+Each timescale object offers an array of Julian dates ``leap_dates``
+and another array of the same length named ``leap_offsets``
+that offers the difference between UTC and TAI in seconds:
+
+.. testcode::
+
+    ts = load.timescale()
+    for jd, offset in zip(ts.leap_dates, ts.leap_offsets):
+        ymd = ts.tt_jd(jd).tt_strftime('%Y-%m-%d')
+        print(jd, ymd, '{:+}'.format(int(offset)))
+
+.. testoutput::
+
+    2441499.5 1972-07-01 +11
+    2441683.5 1973-01-01 +12
+    2442048.5 1974-01-01 +13
+    ...
+    2456109.5 2012-07-01 +35
+    2457204.5 2015-07-01 +36
+    2457754.5 2017-01-01 +37
+
+Note that each leap second occurs just before
+the Julian date given in the table.
+Taking the second row as an example,
+the offset between TAI and UTC increased to +12
+at the first moment of the day 1973-01-01.
+It did so because that day was immediately preceded by a leap second
+that was attached to the *previous* day as its final second.
+So the leap second followed the normal, non-leap second 1972-12-31 12:59:59
+and had the special designation 1972-12-31 12:59:60.
+
 ----------------------------------
 Bad performance and using 100% CPU
 ----------------------------------
diff --git a/skyfield/documentation/time.rst b/skyfield/documentation/time.rst
index e3916eeca..349451638 100644
--- a/skyfield/documentation/time.rst
+++ b/skyfield/documentation/time.rst
@@ -335,6 +335,9 @@ while keeping UTC synchronized with the Earth
 is to occasionally add an extra leap second
 to one of the year’s minutes.
 
+See :ref:`the-leap-second-table` if you are interested
+in printing Skyfield’s full list of leap seconds.
+
 The `International Earth Rotation Service <http://hpiers.obspm.fr/>`_
 currently restricts itself to appending a leap second
 to the last minute of June or the last minute of December.
diff --git a/skyfield/positionlib.py b/skyfield/positionlib.py
index 04e4b0bd6..cb71b9b0e 100644
--- a/skyfield/positionlib.py
+++ b/skyfield/positionlib.py
@@ -293,7 +293,7 @@ def hadec(self):
         Because this declination is measured from the plane of the
         Earth’s physical geographic equator, it will be slightly
         different than the declination returned by ``radec()`` if you
-        have loaded a :ref:`polar motion` file.
+        have loaded a :ref:`polar-motion` file.
 
         The coordinates are not adjusted for atmospheric refraction near
         the horizon.