Update sphinx docs; use exhale and breathe.

.gitignore

@@ -5,3 +5,5 @@
 /docs/html/
 /docs/latex/
 /docs/xml/
+docs/sphinx/_build/
+docs/sphinx/api/

docs/sphinx/api.rst

@@ -1,4 +0,0 @@
-wrmath API
-==========
-
-.. doxygenindex::

docs/sphinx/conf.py

@@ -31,7 +31,8 @@ release = '0.0.1'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-        'breathe',
+    'breathe',
+    'exhale',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -48,7 +49,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -58,3 +59,23 @@ html_static_path = ['_static']
 # -- Options for breathe output ----------------------------------------------
 breathe_projects = {'wrmath': '../xml/'}
 breathe_default_project = 'wrmath'
+
+
+# -- Options for exhale output -----------------------------------------------
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./api",
+    "rootFileName":          "wrmath.rst",
+    "rootFileTitle":         "libwrmath API",
+    "doxygenStripFromPath":  "..",
+    # Suggested optional arguments
+    "createTreeView":        True,
+    #"exhaleExecutesDoxygen": True,
+    #"exhaleDoxygenStdin":    "INPUT = ../include"
+}
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = 'cpp'
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = 'cpp'

docs/sphinx/index.rst

@@ -3,14 +3,23 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to wrmath's documentation!
-==================================
+libwrmath: WNTRMUTE ROBOTICS' maths library
+===========================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    api
+   vector
+   quaternion
+   resources
+   api/wrmath
+
+
+``wrmath`` is a maths library aimed at robotics and navigation
+applications. It provides classes for certain mathematics 
+structures (e.g. :ref:`Vectors <vector-docs>`).
 
 
 Indices and tables

docs/sphinx/overview.rst

@@ -0,0 +1,26 @@
+.. _wrmath_api:
+
+Quick Overview
+==============
+
+Namespaces
+----------
+
+All WNTRMUTE code is in the ``wr`` namespace. The ``geom`` class is
+used for code concerning itself with realspace, e.g. :ref:`Quaternions
+<quaternion-docs>`.
+
+Coordinate systems
+------------------
+
+The library uses a left-hand coordinate system where +x is north, +y is
+east, and +z is up. Accordingly, where Euler angles are concerned, the
+ZYX (yaw / pitch / roll) axes are used.
+
+Important classes
+-----------------
+
+The foundational class of this library (and here's to a real mathematical
+workhorse) is the :class:`wr::geom::Vector`` class.
+
+Other important classes are the :class:`wr::geom::Quaternion` class.

docs/sphinx/quaternion.rst

@@ -0,0 +1,77 @@
+.. _quaternion-docs:
+.. highlight:: c++
+
+Quaternions
+===========
+
+Examples taken from the unit tests::
+
+  TEST(Quaterniond, Rotate)
+  {
+          // This test aims to rotate a vector v using a quaternion.
+          // c.f. https://math.stackexchange.com/questions/40164/
+	  //
+          // If we assume a standard IMU frame of reference following the
+          // right hand rule:
+          // + The x axis points toward magnetic north
+          // + The y axis points toward magnentic east
+          // + The z axis points toward the sky
+          // Given a vector pointing due north, rotating by 90º about
+          // the y-axis should leave us pointing toward the sky.
+  
+          geom::Vector3d          v {1.0, 0.0, 0.0};     // a vector pointed north
+          geom::Vector3d          yAxis {0.0, 1.0, 0.0}; // a vector representing the y axis.
+          double                  angle = M_PI / 2;      // 90º rotation
+  
+          // A quaternion representing a 90º rotation about the y axis.
+          geom::Quaterniond       p = geom::quaterniond(yAxis, angle);
+          geom::Vector3d          vr {0.0, 0.0, 1.0};    // expected rotated vector.
+  
+          // A rotation quaternion should be a unit quaternion.
+          EXPECT_TRUE(p.isUnitQuaternion());
+          EXPECT_EQ(p.rotate(v), vr);
+  }
+  
+  
+  TEST(Quaterniond, ShortestSLERP)
+  {
+          // Our starting point is an orientation that is yawed 45° - our
+          // orientation is pointed π/4 radians in the X axis.
+          geom::Quaterniond       p {0.382683, 0, 0, 0.92388};
+
+          // Our ending point is an orientation that is yawed -45° - or
+          // pointed -π/4 radians in the X axis.
+          geom::Quaterniond       q {-0.382683, 0, 0, 0.92388};
+
+          // The halfway point should be oriented midway about the X axis. It turns
+          // out this is an identity quaternion.
+          geom::Quaterniond       r;
+  
+          EXPECT_EQ(geom::ShortestSLERP(p, q, 0.0), p);
+          EXPECT_EQ(geom::ShortestSLERP(p, q, 1.0), q);
+          EXPECT_EQ(geom::ShortestSLERP(p, q, 0.5), r);
+  }
+  
+  
+  TEST(Quaterniond, ShortestSLERP2)
+  {
+          // Start with an orientation pointing forward, all Euler angles
+          // set to 0.
+          geom::Quaterniond       start {0.0, 0.0, 0.0, 1.0};
+          // The goal is to end up face up, or 90º pitch (still facing forward).
+          geom::Quaterniond       end {0, -0.707107, 0, 0.707107};
+          // Halfway to the endpoint should be a 45º pitch.
+          geom::Quaterniond       halfway {0, -0.382683, 0, 0.92388 };
+          // 2/3 of the way should be 60º pitch.
+          geom::Quaterniond       twoThirds {0, -0.5, 0, 0.866025};
+  
+          EXPECT_EQ(ShortestSLERP(start, end, 0.0), start);
+          EXPECT_EQ(ShortestSLERP(start, end, 1.0), end);
+          EXPECT_EQ(ShortestSLERP(start, end, 0.5), halfway);
+          EXPECT_EQ(ShortestSLERP(start, end, 2.0/3.0), twoThirds);
+  }
+
+
+.. doxygenclass:: wr::geom::Quaternion
+   :members:
+

docs/sphinx/requirements.txt

@@ -1,2 +1,4 @@
 sphinx
 breathe
+sphinx_rtd_theme
+exhale

docs/sphinx/resources.rst

@@ -0,0 +1,21 @@
+.. _resources:
+
+Resources
+=========
+
+This is a collection of useful documents for things.
+
+Quaternions
+-----------
+
++ As usual, `3Blue1Brown <https://www.3blue1brown.com/>`_ has a `good set
+  of videos <https://eater.net/quaternions>`_ on the subject.
++ `Intro to Quaternions <https://www.youtube.com/watch?v=fKIss4EV6ME>`_ is
+  another great video tutorial.
++ `Quaternions and Rotations <http://graphics.stanford.edu/courses/cs348a-17-winter/Papers/quaternion.pdf>`_
+  is a set of useful class notes.
++ `Understanding Quaternions <http://www.chrobotics.com/library/understanding-quaternions>`_
+  and
+  `Understanding Euler Angles <http://www.chrobotics.com/library/understanding-euler-angles>`_
+  approaches quaternions from the standpoint of attitude and orientation.
+

docs/sphinx/vector.rst

@@ -0,0 +1,33 @@
+.. _vector-docs:
+.. highlight:: c++
+
+Vectors
+=======
+
+Examples taken from the unit tests::
+
+  TEST(Vector3FloatTests, Projections)
+  {
+          geom::Vector3f  a {4.866769214609107, 6.2356222686140566, 9.140878417029711};
+          geom::Vector3f  b {6.135533104801077, 8.757851406697895, 0.6738031370548048};
+          geom::Vector3f  c {4.843812341655318, 6.9140509888133055, 0.5319465962229454};
+          geom::Vector3f  d {0.02295687295378901, -0.6784287201992489, 8.608931820806765};
+  
+          ASSERT_EQ(a.projectParallel(b), c);
+          ASSERT_EQ(a.projectOrthogonal(b), d);
+  }
+  
+  
+  TEST(Vector3FloatTests, CrossProduct)
+  {
+          geom::Vector3f  a {8.462, 7.893, -8.187};
+          geom::Vector3f  b {6.984, -5.975, 4.778};
+          geom::Vector3f  c {-11.2046, -97.6094, -105.685};
+  
+          c.setEpsilon(0.001);
+          EXPECT_EQ(c, a.cross(b));
+  }
+
+
+.. doxygenclass:: wr::geom::Vector
+   :members:

update-docs

@@ -0,0 +1,12 @@
+#!/bin/sh
+set +eux
+
+if [ "$(hostname -s)" = "freeside" ]
+then
+	HOST="$HOME/"
+else
+	HOST="freeside.wntrmute.net:"
+fi
+
+cd docs && doxygen && rsync -auv html/ ${HOST}sites/wntrmute-dev/wrmath/
+cd sphinx && make html && rsync -auv _build/html/ ${HOST}sites/wntrmute-dev/sphinx/