Add LaTeX formatting to doc comments (#118)

There are a few places where a bit of LaTeX would help make things a bit
more clear in our documentation. Indeed the C library documentation has
several uses of LaTeX which Doxygen handles. This is based on the
[rustdoc-katex-demo](https://github.com/paulkernfeld/rustdoc-katex-demo)
crate, which demonstates how to include a link to the KaTex code in the
HTML generated for the documents.

Author: jbangelo

katex-header.html

@@ -0,0 +1,15 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha256-GQlRJzV+1tKf4KY6awAMkTqJ9/GWO3Zd03Fel8mFLnU=" crossorigin="anonymous">
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js" integrity="sha256-6NiFUFlJ86X0q91d0NU2lr0Tca0m/79PMQ3Nd8jNrok=" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js" integrity="sha256-u1PrlTOUUxquNv3VNwZcQkTrhUKQGjzpFGAdkyZ1uKw=" crossorigin="anonymous"></script>
+<script>
+    document.addEventListener("DOMContentLoaded", function() {
+        renderMathInElement(document.body, {
+            delimiters: [
+                {left: "$$", right: "$$", display: true},
+                {left: "\\(", right: "\\)", display: false},
+                {left: "$", right: "$", display: false},
+                {left: "\\[", right: "\\]", display: true}
+            ]
+        });
+    });
+</script>

swiftnav/Cargo.toml

@@ -17,3 +17,9 @@ strum = { version = "0.27", features = ["derive"] }
 
 [dev-dependencies]
 float_eq = "1.0.1"
+
+# This tells docs.rs to include the katex header for math formatting
+# To do this locally 
+[package.metadata.docs.rs]
+rustdoc-args = [ "--html-in-header", "katex-header.html" ]
+

swiftnav/src/coords.rs

@@ -17,16 +17,18 @@
 //!
 //! --------
 //! Conversion from geodetic coordinates latitude, longitude and height
-//! (ϕ, λ, h) into Cartesian coordinates (X, Y, Z) can be
+//! ($\phi$, $\lambda$, $h$) into Cartesian coordinates ($X$, $Y$, $Z$) can be
 //! achieved with the following formulae:
-//!  * X = (N(ϕ) + h) * cos(ϕ) * cos(λ)
-//!  * Y = (N(ϕ) + h) * cos(ϕ) * sin(λ)
-//!  * Z = [(1-e^2) * N(ϕ) + h] * sin(ϕ)
 //!
-//! Where the 'radius of curvature', N(ϕ), is defined as:
-//!  * N(ϕ) = a / sqrt(1-e^2 / sin^2(ϕ))
+//! $$X = (N(\phi) + h) \cos{\phi}\cos{\lambda}$$
+//! $$Y = (N(\phi) + h) \cos{\phi}\sin{\lambda}$$
+//! $$Z = \left[(1-e^2)N(\phi) + h\right] \sin{\phi}$$
 //!
-//! and `a` is the WGS84 semi-major axis and `e` is the WGS84
+//! Where the 'radius of curvature', $N(\phi)$, is defined as:
+//!
+//! $$N(\phi) = \frac{a}{\sqrt{1-e^2\sin^2 \phi}}$$
+//!
+//! and $a$ is the WGS84 semi-major axis and $e$ is the WGS84
 //! eccentricity.
 //!
 //! --------

swiftnav/src/edc.rs

@@ -14,8 +14,10 @@
 /// This CRC is used with the RTCM protocol
 ///
 /// The CRC polynomial used is:
+/// $$[
 ///   x^{24} + x^{23} + x^{18} + x^{17} + x^{14} + x^{11} + x^{10} +
 ///   x^7    + x^6    + x^5    + x^4    + x^3    + x+1
+/// ]$$
 ///
 /// Mask 0x1864CFB, not reversed, not XOR'd
 pub fn compute_crc24q(buf: &[u8], initial_value: u32) -> u32 {

swiftnav/src/reference_frame/mod.rs

@@ -138,18 +138,34 @@ pub enum ReferenceFrame {
 
 /// 15-parameter Helmert transformation parameters
 ///
-/// This transformation consists of a 3 dimensional translation,
-/// 3 dimensional rotation, and a universal scaling. All terms,
-/// except for the reference epoch, have a an additional time
-/// dependent term. The rotations are typically very small, so
-/// the small angle approximation is used.
+/// This is an extension of the 7-parameter Helmert transformation
+/// where each term has an additional time-dependent term. This
+/// transformation consists of a 3 dimensional translation,
+/// 3 dimensional rotation, and a universal scaling. The tranformation
+/// takes the form of:
 ///
-/// There are several sign and scale conventions in use with
-/// Helmert transformations. In this implementation we follow
-/// the IERS conventions, meaning the translations are in
-/// millimeters, the rotations are in milliarcseconds, and
-/// the scaling is in parts per billion. We also follow the
-/// IERS convention for the sign of the rotation terms.
+/// $$
+///  \begin{bmatrix} X \\\\ Y \\\\ Z \end{bmatrix}\_{REF2} =
+///  \begin{bmatrix} X \\\\ Y \\\\ Z \end{bmatrix}\_{REF1} +
+///  \begin{bmatrix} \bar{t}_x \\\\ \bar{t}_y \\\\ \bar{t}_z \end{bmatrix} +
+///  \begin{bmatrix}   \bar{s} & -\bar{r}_z & \bar{r}_y \\\\
+///                    \bar{r}_z & \bar{s} & -\bar{r}_x \\\\
+///                    -\bar{r}_y  & \bar{r}_x & \bar{s} \end{bmatrix}
+///  \begin{bmatrix} X \\\\ Y \\\\ Z \end{bmatrix}\_{REF1}
+/// $$
+///
+/// Where each $\bar{}$ parameter in the transformation is time
+/// dependent and is defined to be:
+///
+/// $$ \bar{p}(t) = p + \dot{p}(t - \tau) $$
+///
+/// Where $p$ is the constant value, $\dot{p}$ is the rate of
+/// change, and $\tau$ is the reference epoch.
+///
+/// There are several sign conventions in use for the rotation
+/// parameters in Helmert transformations. In this implementation
+/// we follow the IERS conventions, which is opposite of the original
+/// formulation of the Helmert transformation.
 #[derive(Debug, PartialEq, PartialOrd, Clone, Copy)]
 pub struct TimeDependentHelmertParams {
     tx: f64,