Refactor the documentation tutorials (#130)

Shifted the focus to how to do things with Boule and point to other pages (like
the new glossary and docstrings) for more of the theory. Gravity disturbance
tutorial expanded a bit to be more in line with the Harmonica tutorial.
Coordinate conversion tutorial was refocused on using pymap3d instead of
explaining what the coordinate systems are, which should be in a separate page.

boule/_ellipsoid.py

@@ -543,9 +543,9 @@ def normal_gravity(self, latitude, height, si_units=False):
         Normal gravity of the ellipsoid at the given latitude and height.
 
         Computes the magnitude of the gradient of the gravity potential
-        (gravitational + centrifugal; see [Heiskanen-Moritz]_) generated by the
-        ellipsoid at the given geodetic latitude :math:`\phi` and height above
-        the ellipsoid :math:`h` (geometric height).
+        (gravitational + centrifugal; see [HofmannWellenhofMoritz2006]_)
+        generated by the ellipsoid at the given geodetic latitude :math:`\phi`
+        and height above the ellipsoid :math:`h` (geometric height).
 
         .. math::
 

boule/_realizations.py

@@ -103,8 +103,7 @@
     angular_velocity=326.71050958367e-6,
     reference=(
         "Russell, C. T., Raymond, C. A., Coradini, A., McSween, H. Y., Zuber, "
-        "M. T., Nathues, A., et al. (2012, May 11). Dawn at Vesta: Testing "
-        "the Protoplanetary Paradigm. Science. "
-        "doi:10.1126/science.1219381"
+        "M. T., Nathues, A., et al. (2012). Dawn at Vesta: Testing the "
+        "Protoplanetary Paradigm. Science. doi:10.1126/science.1219381"
     ),
 )

boule/_sphere.py

@@ -179,9 +179,9 @@ def normal_gravity(self, latitude, height, si_units=False):
         Normal gravity of the sphere at the given latitude and height.
 
         Computes the magnitude of the gradient of the gravity potential
-        (gravitational + centrifugal; see [Heiskanen-Moritz]_) generated by the
-        sphere at the given spherical latitude :math:`\theta` and height above
-        the surface of the sphere :math:`h`:
+        (gravitational + centrifugal; see [HofmannWellenhofMoritz2006]_)
+        generated by the sphere at the given spherical latitude :math:`\theta`
+        and height above the surface of the sphere :math:`h`:
 
         .. math::
 

boule/_triaxialellipsoid.py

@@ -34,7 +34,8 @@ class TriaxialEllipsoid:
 
         Gravity calculations have not been implemented yet for triaxial
         ellipsoids. If you're interested in this feature or would like to help
-        implement, please `get in touch <https://www.fatiando.org/contact>`__.
+        implement it, please
+        `get in touch <https://www.fatiando.org/contact>`__.
 
     Parameters
     ----------
@@ -48,7 +49,7 @@ class TriaxialEllipsoid:
         The semimedium (middle) axis of the ellipsoid.
         Definition: :math:`b`.
         Units: :math:`m`.
-    semimajor_axis : float
+    semiminor_axis : float
         The semiminor (smallest) axis of the ellipsoid.
         Definition: :math:`c`.
         Units: :math:`m`.

doc/api/index.rst

@@ -7,16 +7,13 @@ List of functions and classes (API)
 
 .. currentmodule:: boule
 
-Reference Ellipsoid
--------------------
+All :ref:`available ellipsoids <ellipsoids>` are instances of these classes.
+See the class documentation for a list their derived physical properties
+(attributes) and computations/transformations that they can perform (methods).
 
 .. autosummary::
    :toctree: generated/
 
     Ellipsoid
     Sphere
     TriaxialEllipsoid
-
-All ellipsoids are instances of these classes. See the class reference
-documentation for a list their derived physical properties (attributes) and
-computations/transformations that they can perform (methods).

doc/conf.py

@@ -38,9 +38,11 @@
 # functions/classes
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
     "pygmt": ("https://www.pygmt.org/latest/", None),
     "ensaio": ("https://www.fatiando.org/ensaio/latest/", None),
+    "verde": ("https://www.fatiando.org/verde/latest/", None),
 }
 
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build

doc/ellipsoids.rst

@@ -0,0 +1,79 @@
+.. _ellipsoids:
+
+Available ellipsoids
+====================
+
+These are the available ellipsoids and their corresponding defining parameters.
+
+All ellipsoids are instances of the :class:`~boule.Ellipsoid`,
+:class:`~boule.Sphere`, or :class:`~boule.TriaxialEllipsoid` classes. See the
+class documentations for a list their derived physical properties (attributes)
+and computations/transformations that they can perform (methods).
+
+.. jupyter-execute::
+    :hide-code:
+
+    import boule
+
+
+Earth
+-----
+
+The **WGS84 (World Geodetic System 1984)** ellipsoid as defined by the values
+given in [HofmannWellenhofMoritz2006]_:
+
+.. jupyter-execute::
+
+    print(boule.WGS84)
+
+The **GRS80 (Geodetic Reference System 1980)** ellipsoid as defined by the
+values given in [HofmannWellenhofMoritz2006]_:
+
+.. jupyter-execute::
+
+    print(boule.GRS80)
+
+Moon
+----
+
+The parameters of the Lunar spheroid were obtained from [Wieczorek2015]_:
+
+.. jupyter-execute::
+
+    print(boule.MOON)
+
+Mars
+----
+
+The parameters of the Martian ellipsoid were obtained from [Ardalan2009]_:
+
+.. jupyter-execute::
+
+    print(boule.MARS)
+
+Mercury
+-------
+
+The parameters of the Mercurian spheroid were obtained from [Wieczorek2015]_:
+
+.. jupyter-execute::
+
+    print(boule.MERCURY)
+
+Venus
+-----
+
+The parameters of the Venusian spheroid were obtained from [Wieczorek2015]_:
+
+.. jupyter-execute::
+
+    print(boule.VENUS)
+
+Vesta
+-----
+
+The parameters of the Vesta triaxial ellipsoid were obtained from [Russell2012]_:
+
+.. jupyter-execute::
+
+    print(boule.VESTA)