Update sphinx docs; use exhale and breathe.

This commit is contained in:
Kyle Isom 2019-08-07 01:57:26 +00:00
parent 48729670c1
commit 7a932f422a
10 changed files with 209 additions and 10 deletions

2
.gitignore vendored
View File

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

View File

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

View File

@ -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'

View File

@ -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

26
docs/sphinx/overview.rst Normal file
View File

@ -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.

View File

@ -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:

View File

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

21
docs/sphinx/resources.rst Normal file
View File

@ -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.

33
docs/sphinx/vector.rst Normal file
View File

@ -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:

12
update-docs Executable file
View File

@ -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/