Fix all dangling cross references in the docs

CHANGELOG.rst

@@ -59,8 +59,8 @@ Changelog
   whether Earth satellites in orbit are in Earth’s shadow or not, thanks
   to a pull request from Jesse Coffey.
 
-* Added :func:`~skyfield.positionlib.position_of_radec()` to replace the
-  poorly designed :func:`~skyfield.positionlib.position_from_radec()`.
+* Added :func:`~skyfield.positionlib.position_of_radec()`
+  to replace the poorly designed ``position_from_radec()``.
 
 * Skyfield :class:`~skyfield.timelib.Time` objects now have microsecond
   internal accuracy, so round trips to and from Python datetimes should
@@ -187,7 +187,7 @@ Changelog
   `#296 <https://github.com/skyfielders/python-skyfield/issues/296>`_
   `#297 <https://github.com/skyfielders/python-skyfield/issues/297>`_
 
-* Added a :func:`~skyfield.almanac.rising_setting()` function for
+* Added a :func:`~skyfield.almanac.risings_and_settings()` function for
   computing rising and setting times.
   `#271 <https://github.com/skyfielders/python-skyfield/issues/271>`_
 
@@ -197,7 +197,7 @@ Changelog
 * Provided a constellation lookup routine through
   :func:`~skyfield.api.load_constellation_map()`.
 
-* Added :func:`~skyfield.positionlib.position_from_radec()`.
+* Added a ``position_from_radec()`` function.
 
 * Fixed the ``apparent()`` method in the case where a single observer
   position is observing an entire vector of target positions.
@@ -291,7 +291,7 @@ Changelog
 1.6 — 2018 July 25
 ------------------
 
-* Both of the loader methods :meth:`~skyfield.iokit.Loader.load()` and
+* Both of the loader methods :meth:`~skyfield.iokit.Loader.open()` and
   :meth:`~skyfield.iokit.Loader.tle()` now accept not just URLs but also
   plain local file paths; they correctly re-download a remote file if
   “reload=True” is specified; and they allow specifying a different local
@@ -540,12 +540,13 @@ Changelog
 0.4
 ---
 
-* To prevent confusion, the :meth:`~Time.astimezone()`
-  and :meth:`~Time.utc_datetime()` methods
+* To prevent confusion, the :meth:`~skyfield.timelib.Time.astimezone()`
+  and :meth:`~skyfield.timelib.Time.utc_datetime()` methods
   have been changed to return only a ``datetime`` object.
   If you also need a leap second flag returned,
-  call the new methods :meth:`~Time.astimezone_and_leap_second()`
-  and :meth:`~Time.utc_datetime_and_leap_second()`.
+  call the new methods
+  :meth:`~skyfield.timelib.Time.astimezone_and_leap_second()`
+  and :meth:`~skyfield.timelib.Time.utc_datetime_and_leap_second()`.
 
 0.3
 ---

skyfield/documentation/api-satellites.rst

@@ -10,4 +10,3 @@ satellite data and computing their positions with Skyfield.
 
 .. autoclass:: EarthSatellite
    :members:
-

skyfield/documentation/api.rst

@@ -135,10 +135,12 @@ The common API shared by planets, Earth locations, and Earth satellites.
 .. autosummary::
 
    VectorFunction
-   VectorFunction.__add__
-   VectorFunction.__sub__
    VectorFunction.at
 
+Either adding two vector functions ``v1 + v2`` or subtracting them ``v1 - v2``
+produces a new function of time that, when invoked with ``.at(t)``,
+returns the sum or difference of the vectors returned by the two functions.
+
 Planetary Ephemerides
 =====================
 
@@ -156,7 +158,10 @@ See :doc:`planets`.
    SpiceKernel.comments
    SpiceKernel.names
    SpiceKernel.decode
-   SpiceKernel.__getitem__
+
+Kernels also support lookup using the Python ``kernel['Mars']`` syntax,
+in which case they return a function of time
+that returns vectors from the Solar System barycenter to the named body.
 
 Almanac
 =======
@@ -169,7 +174,6 @@ Routines to search for events like sunrise, sunset, and Moon phase.
 
    phase_angle
    fraction_illuminated
-   find_discrete
    seasons
    sunrise_sunset
    dark_twilight_day
@@ -299,6 +303,15 @@ Constellations
 
 .. autofunction:: skyfield.api.load_constellation_map
 
+Searching
+=========
+
+.. currentmodule:: skyfield.searchlib
+
+.. autofunction:: find_discrete()
+.. autofunction:: find_maxima()
+.. autofunction:: find_minima()
+
 Osculating Orbital Elements
 ===========================
 

skyfield/documentation/earth-satellites.rst

@@ -3,8 +3,6 @@
  Earth Satellites
 ==================
 
-.. currentmodule:: skyfield
-
 Skyfield is able to predict the positions of Earth satellites
 from the Two-Line Element (TLE) files published
 by organizations like `CelesTrak`_.
@@ -276,7 +274,7 @@ at which a particular satellite is overhead,
 you will probably want to learn more about its position at those times.
 
 The simplest form in which you can generate a satellite position
-is to call its :meth:`~skyfield.sgp4lib.EarthSatellite.at()` method,
+is to call its ``at()`` method,
 which will return an *x, y, z* position relative to the Earth’s center
 in the Geocentric Celestial Reference System.
 (GCRS coordinates are based on even more precise axes
@@ -598,7 +596,7 @@ Detecting Propagation Errors
 After building a satellite object,
 you can examine the *epoch* date and time
 when the TLE element set’s predictions are most accurate.
-The ``epoch`` attribute is a :class:`Time`,
+The ``epoch`` attribute is a :class:`~skyfield.timelib.Time`,
 so it supports all of the standard Skyfield date methods:
 
 .. testcode::

skyfield/documentation/files.rst

@@ -3,8 +3,6 @@
  Downloading and Using Data Files
 ==================================
 
-.. currentmodule:: skyfield.api
-
 Your Skyfield programs will typically download two kinds of data file.
 
 First, Skyfield will need up-to-date tables about time —
@@ -67,7 +65,7 @@ and can start up without needing to access the network:
    Ready
 
 Most programs will run just fine using the default ``load()`` object
-provided in the :mod:`skyfield.api` module.
+provided in the ``skyfield.api`` module.
 But other programs may want to build their own loader
 so that they have the chance to specify non-default behavior.
 

skyfield/documentation/planets.rst

@@ -2,8 +2,6 @@
  Planets, and Choosing an Ephemeris
 ====================================
 
-.. currentmodule:: skyfield.api
-
 If you are interested in observing the planets,
 the Jet Propulsion Laboratory (JPL)
 has prepared long tables that predict the positions of the planets
@@ -12,7 +10,7 @@ A table of positions is called an *ephemeris*
 and those supplied by the JPL are of very high accuracy.
 
 You can ask Skyfield to download an ephemeris from the JPL
-by giving :func:`~skyfield.iokit.load()` a filename.
+by giving ``load()`` a filename.
 Or you can load an ephemeris that you’ve already saved to disk
 with :func:`~skyfield.iokit.load_file()`.
 

skyfield/documentation/positions.rst

@@ -3,7 +3,7 @@
  Positions and Coordinates
 ===========================
 
-.. currentmodule:: skyfield.api
+.. currentmodule:: skyfield.positionlib
 
 Skyfield is careful to distinguish the *position* of an object
 from the several choices of *coordinate*
@@ -258,7 +258,7 @@ Instead of using an acronym,
 Skyfield uses the class name :class:`Barycentric`
 for coordinates expressed in the ICRS.
 You can view the raw *x*, *y*, and *z* coordinates
-by asking Skyfield for their :attr:`~Barycentric.position` attribute:
+by asking Skyfield for their ``position`` attribute:
 
 .. testcode::
 
@@ -335,9 +335,9 @@ that we see in our sky:
 This light-delayed position is called the *astrometric* position,
 and is traditionally mapped on a star chart
 by the angles *right ascension* and *declination*
-that you can compute using the :meth:`~Position.radec()` method
-and display using their :meth:`~Angle.hstr()`
-and :meth:`~Angle.dstr()` methods:
+that you can compute using the :meth:`~ICRF.radec()` method
+and display using their :meth:`~skyfield.units.Angle.hstr()`
+and :meth:`~skyfield.units.Angle.dstr()` methods:
 
 .. testcode::
 
@@ -592,7 +592,7 @@ call the
 :meth:`~skyfield.positionlib.ICRF.separation_from()`
 method of one of the positions
 and pass it the other position as its argument.
-The result will be an :class:`~Angle` object.
+The result will be an :class:`~skyfield.units.Angle` object.
 
 If instead you want to know the distance between two positions,
 subtract the position you want to use as the starting point

skyfield/documentation/searches.rst

@@ -14,10 +14,6 @@ that looks for a moment of position or alignment
 that fits some definition that you are looking for.
 The other is an “extremum” search
 where you want to know when a value reaches its maximum or minimum value.
-For the moment,
-this documentation page only discusses searching for events;
-check out the ``find_maxima()`` routine in the ``searchlib.py`` source code
-for how Skyfield searches for maximum or minimum values.
 
 Finding discrete events
 =======================

skyfield/documentation/stars.rst

@@ -3,7 +3,7 @@
  Stars and Distant Objects
 ===========================
 
-.. currentmodule:: skyfield.api
+.. currentmodule:: skyfield.starlib
 
 Skyfield can generate positions for stars or and other distant objects
 that you either load from a star catalog, or else for which you can

skyfield/documentation/time.rst

@@ -26,7 +26,7 @@ The supported time scales are:
 
 To specify a time,
 first build a :class:`Timescale` object
-by calling Skyfield’s :meth:`load.timescale()` routine.
+by calling Skyfield’s ``load.timescale()`` routine.
 This downloads several data files from international authorities —
 the United States Naval Observatory
 and the International Earth Rotation Service —
@@ -799,7 +799,8 @@ or invokes a computation that needs their value:
     this Julian date.
 
 You will typically never need to access these matrices yourself,
-as they are used automatically by the :meth:`Position.radec()`
+as they are used automatically
+by the :meth:`~skyfield.positionlib.ICRF.radec()`
 method when you use its  ``epoch=`` parameter
 to ask for a right ascension and declination
 in the dynamical reference system,

skyfield/searchlib.py

@@ -8,24 +8,11 @@ from .constants import DAY_S
 EPSILON = 0.001 / DAY_S
 
 def find_discrete(start_time, end_time, f, epsilon=EPSILON, num=12):
-    """Find the times when a function changes value.
+    """Find the times at which a discrete function of time changes value.
 
-    Search between ``start_time`` and ``end_time``, which should both be
-    :class:`~skyfield.timelib.Time` objects, for the occasions where the
-    function ``f`` changes from one value to another.  Use this to
-    search for events like sunrise or moon phases.
-
-    A tuple of two arrays is returned. The first array gives the times
-    at which the input function changes, and the second array specifies
-    the new value of the function at each corresponding time.
-
-    This is an expensive operation as it needs to repeatedly call the
-    function to narrow down the times that it changes.  It continues
-    searching until it knows each time to at least an accuracy of
-    ``epsilon`` Julian days.  At each step, it creates an array of
-    ``num`` new points between the lower and upper bound that it has
-    established for each transition.  These two values can be changed to
-    tune the behavior of the search.
+    This routine is used to find instantaneous events like sunrise,
+    transits, and the seasons.  See :doc:`searches` for how to use it
+    yourself.
 
     """
     ts = start_time.ts
@@ -89,6 +76,12 @@ def _find_discrete(ts, jd, f, epsilon, num):
     return ts.tt_jd(ends), y
 
 def find_minima(start_time, end_time, f, epsilon=1.0 / DAY_S, num=12):
+    """Find the local minima in the values returned by a function of time.
+
+    This routine is used to find events like minimum elongation.  See
+    :doc:`searches` for how to use it yourself.
+
+    """
     def g(t): return -f(t)
     g.rough_period = getattr(f, 'rough_period', None)
     g.step_days = getattr(f, 'step_days', None)
@@ -96,6 +89,12 @@ def find_minima(start_time, end_time, f, epsilon=1.0 / DAY_S, num=12):
     return t, -y
 
 def find_maxima(start_time, end_time, f, epsilon=1.0 / DAY_S, num=12):
+    """Find the local maxima in the values returned by a function of time.
+
+    This routine is used to find events like highest altitude and
+    maximum elongation.  See :doc:`searches` for how to use it yourself.
+
+    """
     #    @@       @@_@@       @@_@@_@@_@@
     #   /  \     /     \     /           \
     # @@    @@ @@       @@ @@             @@

skyfield/sgp4lib.py

@@ -19,10 +19,10 @@ _identity = identity(3)
 class EarthSatellite(VectorFunction):
     """An Earth satellite loaded from a TLE file and propagated with SGP4.
 
-    An earth satellite object is a Skyfield vector function, so call its
-    :meth:`~skyfield.vectorlib.VectorSum.at()` method to generate its
-    position in the sky, or use addition and subtraction to combine it
-    with other vectors.
+    An earth satellite object is a Skyfield vector function, so you can
+    either call its ``at()`` method to generate its position in the sky
+    or else use addition and subtraction to combine it with other
+    vectors.
 
     Satellite parameters are generally only accurate for a week or two
     around the *epoch* of the parameters, the date for which they were

skyfield/units.py

@@ -95,6 +95,7 @@ class Distance(object):
         return Distance(au=length_of(self.au))
 
     def light_seconds(self):
+        """Return the length of this vector in light seconds."""
         return self.m / C
 
     def to(self, unit):