From 7a932f422a7ee2983a545db0c10741e509d9b294 Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Wed, 7 Aug 2019 01:57:26 +0000 Subject: [PATCH] Update sphinx docs; use exhale and breathe. --- .gitignore | 2 + docs/sphinx/api.rst | 4 -- docs/sphinx/conf.py | 25 +++++++++++- docs/sphinx/index.rst | 15 +++++-- docs/sphinx/overview.rst | 26 ++++++++++++ docs/sphinx/quaternion.rst | 77 ++++++++++++++++++++++++++++++++++++ docs/sphinx/requirements.txt | 4 +- docs/sphinx/resources.rst | 21 ++++++++++ docs/sphinx/vector.rst | 33 ++++++++++++++++ update-docs | 12 ++++++ 10 files changed, 209 insertions(+), 10 deletions(-) delete mode 100644 docs/sphinx/api.rst create mode 100644 docs/sphinx/overview.rst create mode 100644 docs/sphinx/quaternion.rst create mode 100644 docs/sphinx/resources.rst create mode 100644 docs/sphinx/vector.rst create mode 100755 update-docs diff --git a/.gitignore b/.gitignore index 030b574..62c4dfc 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,5 @@ /docs/html/ /docs/latex/ /docs/xml/ +docs/sphinx/_build/ +docs/sphinx/api/ diff --git a/docs/sphinx/api.rst b/docs/sphinx/api.rst deleted file mode 100644 index 8f5ac19..0000000 --- a/docs/sphinx/api.rst +++ /dev/null @@ -1,4 +0,0 @@ -wrmath API -========== - -.. doxygenindex:: diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index c9dca21..c724b97 100644 --- a/docs/sphinx/conf.py +++ b/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' diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index 2135118..c1dcea6 100644 --- a/docs/sphinx/index.rst +++ b/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 `). Indices and tables diff --git a/docs/sphinx/overview.rst b/docs/sphinx/overview.rst new file mode 100644 index 0000000..4d803af --- /dev/null +++ b/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 +`. + +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. diff --git a/docs/sphinx/quaternion.rst b/docs/sphinx/quaternion.rst new file mode 100644 index 0000000..bbe1012 --- /dev/null +++ b/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: + diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt index 4897b0a..63f31bd 100644 --- a/docs/sphinx/requirements.txt +++ b/docs/sphinx/requirements.txt @@ -1,2 +1,4 @@ sphinx -breathe \ No newline at end of file +breathe +sphinx_rtd_theme +exhale diff --git a/docs/sphinx/resources.rst b/docs/sphinx/resources.rst new file mode 100644 index 0000000..57b41a3 --- /dev/null +++ b/docs/sphinx/resources.rst @@ -0,0 +1,21 @@ +.. _resources: + +Resources +========= + +This is a collection of useful documents for things. + +Quaternions +----------- + ++ As usual, `3Blue1Brown `_ has a `good set + of videos `_ on the subject. ++ `Intro to Quaternions `_ is + another great video tutorial. ++ `Quaternions and Rotations `_ + is a set of useful class notes. ++ `Understanding Quaternions `_ + and + `Understanding Euler Angles `_ + approaches quaternions from the standpoint of attitude and orientation. + diff --git a/docs/sphinx/vector.rst b/docs/sphinx/vector.rst new file mode 100644 index 0000000..0993c76 --- /dev/null +++ b/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: diff --git a/update-docs b/update-docs new file mode 100755 index 0000000..ccde62d --- /dev/null +++ b/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/