Port to RTD Sphinx + Doxygen documentation system.

Rebased (squash) commit to reduce Git history noise with added/removed files.

Original authors of squashed commits: @jpsnir , @jlblancoc

Initial commit - docs created

initial commit 2 - checking the webhook settings

Add explicit RTD configuration file

compiled cholesky.lyx to .pdf

modified toc tree

toc tree - initial outline

Use RTD theme; progress with TOC

added FAQs

generate Doxygen for C++ API

minor python linter fixes

Fixed integration Doxygen

Reorganize dox files

Build doxygen in local builds too

Progress converting former GTSAM tutorial to RST

.gitignore

@@ -22,3 +22,4 @@ cython/gtsam_wrapper.pxd
 # for QtCreator:
 CMakeLists.txt.user*
 xcode/
+docs/build

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+#formats:
+#  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+#  install:
+#    - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/.gitignore

@@ -0,0 +1,4 @@
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/Bindings.rst

@@ -0,0 +1,18 @@
+Bindings
+=============
+
+
+GTSAM provides two native C++11 libraries ``gtsam`` and ``gtsam_unstable``.
+Both are also wrapped into other languages for easy prototyping.
+
+
+Python wrapper
+--------------------
+
+Write me!
+
+
+Matlab wrapper
+--------------------
+
+Write me!

docs/source/Building.rst

@@ -0,0 +1,4 @@
+Building
+================
+
+From: https://gtsam.org/build/

docs/source/CppExamples.rst

@@ -0,0 +1,18 @@
+C++ Examples
+==============
+
+
+(Some selected examples from source code.)
+
+
+
+Kalman filter example
+------------------------
+
+
+2D SLAM example
+------------------
+
+
+3D SLAM example
+------------------

docs/source/FactorGraphs.rst

@@ -0,0 +1,50 @@
+Factor Graphs
+---------------
+
+Let us start with a one-page primer on factor graphs, which in no way
+replaces the excellent and detailed reviews by `Kschischang et
+al. <#LyXCite-Kschischang01it>`__ (2001) and
+`Loeliger <#LyXCite-Loeliger04spm>`__ (2004).
+
+
+|image: 2\_Users\_dellaert\_git\_github\_doc\_images\_hmm.png| Figure 1:
+An HMM, unrolled over three time-steps, represented by a Bayes net.
+
+Figure `1 <#fig_unrolledHMM>`__ shows the **Bayes network** for a hidden
+Markov model (HMM) over three time steps. In a Bayes net, each node is
+associated with a conditional density: the top Markov chain encodes the
+prior :math:`P\left( X_{1} \right)` and transition probabilities
+:math:`P\left( X_{2} \middle| X_{1} \right)` and
+:math:`P\left( X_{3} \middle| X_{2} \right)`, whereas measurements
+:math:`Z_{t}` depend only on the state :math:`X_{t}`, modeled by
+conditional densities :math:`P\left( Z_{t} \middle| X_{t} \right)`.
+Given known measurements :math:`z_{1}`, :math:`z_{2}` and :math:`z_{3}`
+we are interested in the hidden state sequence
+:math:`\left( {X_{1},X_{2},X_{3}} \right)` that maximizes the posterior
+probability
+:math:`P\left( X_{1},X_{2},X_{3} \middle| Z_{1} = z_{1},Z_{2} = z_{2},Z_{3} = z_{3} \right)`.
+Since the measurements :math:`Z_{1}`, :math:`Z_{2}`, and :math:`Z_{3}`
+are *known*, the posterior is proportional to the product of six
+**factors**, three of which derive from the the Markov chain, and three
+likelihood factors defined as
+:math:`L\left( {X_{t};z} \right) \propto P\left( Z_{t} = z \middle| X_{t} \right)`:
+
+.. math:: P\left( X_{1},X_{2},X_{3} \middle| Z_{1},Z_{2},Z_{3} \right) \propto P\left( X_{1} \right)P\left( X_{2} \middle| X_{1} \right)P\left( X_{3} \middle| X_{2} \right)L\left( {X_{1};z_{1}} \right)L\left( {X_{2};z_{2}} \right)L\left( {X_{3};z_{3}} \right)
+
+|image: 3\_Users\_dellaert\_git\_github\_doc\_images\_hmm-FG.png| Figure
+2: An HMM with observed measurements, unrolled over time, represented as
+a factor graph.
+
+This motivates a different graphical model, a **factor graph**, in which
+we only represent the unknown variables :math:`X_{1}`, :math:`X_{2}`,
+and :math:`X_{3}`, connected to factors that encode probabilistic
+information on them, as in Figure `2 <#fig_HMM_FG>`__. To do maximum
+a-posteriori (MAP) inference, we then maximize the product
+
+.. math:: f\left( {X_{1},X_{2},X_{3}} \right) = \prod f_{i}\left( \mathcal{X}_{i} \right)
+
+\ i.e., the value of the factor graph. It should be clear from the
+figure that the connectivity of a factor graph encodes, for each factor
+:math:`f_{i}`, which subset of variables :math:`\mathcal{X}_{i}` it
+depends on. In the examples below, we use factor graphs to model more
+complex MAP inference problems in robotics.

docs/source/Installing.rst

@@ -0,0 +1,12 @@
+Installing
+================
+
+Getting started
+------------------
+
+Importing GTSAM in your projects
+-----------------------------------
+
+
+Write your first GTSAM program
+---------------------------------

docs/source/KeyConcepts.rst

@@ -0,0 +1,27 @@
+Key Concepts
+============
+
+
+Bayesian inference using Factor graphs
+--------------------------------------
+
+The Maximum-a-Posteriori Problem
+--------------------------------
+
+Full smoothing problem
+----------------------
+
+Fixed lag smoothing problem
+---------------------------
+
+Filtering problem
+-----------------
+
+IMU Preintegration Factors
+-----------------------------
+
+Solvers
+-----------
+
+Bayes tree
+-------------

docs/source/LandmarkBasedSLAM.rst

@@ -0,0 +1,124 @@
+Landmark-based SLAM
+---------------------
+
+Basics
+~~~~~~~~~~
+
+|image: 12\_Users\_dellaert\_git\_github\_doc\_images\_FactorGraph4.png|
+Figure 10: Factor graph for landmark-based SLAM
+
+In **landmark-based SLAM**, we explicitly build a map with the location
+of observed landmarks, which introduces a second type of variable in the
+factor graph besides robot poses. An example factor graph for a
+landmark-based SLAM example is shown in Figure `10 <#fig_SLAM>`__, which
+shows the typical connectivity: poses are connected in an odometry
+Markov chain, and landmarks are observed from multiple poses, inducing
+binary factors. In addition, the pose :math:`x_{1}` has the usual prior
+on it.
+
+|image: 13\_Users\_dellaert\_git\_github\_doc\_images\_example2.png|
+Figure 11: The optimized result along with covariance ellipses for both
+poses (in green) and landmarks (in blue). Also shown are the trajectory
+(red) and landmark sightings (cyan).
+
+The factor graph from Figure `10 <#fig_SLAM>`__ can be created using the
+MATLAB code in Listing `5.1 <#listing_PlanarSLAMExample>`__. As before,
+on line 2 we create the factor graph, and Lines 8-18 create the
+prior/odometry chain we are now familiar with. However, the code on
+lines 20-25 is new: it creates three **measurement factors**, in this
+case “bearing/range” measurements from the pose to the landmark.
+
+::
+
+    % Create graph container and add factors to it
+    graph = NonlinearFactorGraph;
+
+    % Create keys for variables
+    i1 = symbol('x',1); i2 = symbol('x',2); i3 = symbol('x',3);
+    j1 = symbol('l',1); j2 = symbol('l',2);
+
+    % Add prior
+    priorMean = Pose2(0.0, 0.0, 0.0); % prior at origin
+    priorNoise = noiseModel.Diagonal.Sigmas([0.3; 0.3; 0.1]);
+    % add directly to graph
+    graph.add(PriorFactorPose2(i1, priorMean, priorNoise));
+
+    % Add odometry
+    odometry = Pose2(2.0, 0.0, 0.0);
+    odometryNoise = noiseModel.Diagonal.Sigmas([0.2; 0.2; 0.1]);
+    graph.add(BetweenFactorPose2(i1, i2, odometry, odometryNoise));
+    graph.add(BetweenFactorPose2(i2, i3, odometry, odometryNoise));
+
+    % Add bearing/range measurement factors
+    degrees = pi/180;
+    brNoise = noiseModel.Diagonal.Sigmas([0.1; 0.2]);
+    graph.add(BearingRangeFactor2D(i1, j1, Rot2(45*degrees), sqrt(8), brNoise));
+    graph.add(BearingRangeFactor2D(i2, j1, Rot2(90*degrees), 2, brNoise));
+    graph.add(BearingRangeFactor2D(i3, j2, Rot2(90*degrees), 2, brNoise));
+
+Of Keys and Symbols
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The only unexplained code is on lines 4-6: here we create integer keys
+for the poses and landmarks using the ***symbol*** function. In GTSAM,
+we address all variables using the ***Ke***\ **y** type, which is just a
+typedef to ***size\_t*** a 32 or 64 bit integer,
+depending on your platform. The keys do not have to be numbered continuously, but they do have to
+be unique within a given factor graph. For factor graphs with different
+types of variables, we provide the ***symbol*** function in MATLAB, and
+the ***Symbol*** type in C++, to help you create (large) integer keys
+that are far apart in the space of possible keys, so you don't have to
+think about starting the point numbering at some arbitrary offset. To
+create a a *symbol key* you simply provide a character and an integer
+index. You can use base 0 or 1, or use arbitrary indices: it does not
+matter. In the code above, we we use 'x' for poses, and 'l' for
+landmarks.
+
+The optimized result for the factor graph created by Listing
+`5.1 <#listing_PlanarSLAMExample>`__ is shown in Figure
+`11 <#fig_PlanarSLAMExample>`__, and it is readily apparent that the
+landmark :math:`l_{1}` with two measurements is better localized. In
+MATLAB we can also examine the actual numerical values, and doing so
+reveals some more GTSAM magic:
+
+>> result Values with 5 values: l1: (2, 2) l2: (4, 2) x1: (-1.8e-16,
+5.1e-17, -1.5e-17) x2: (2, -5.8e-16, -4.6e-16) x3: (4, -3.1e-15,
+-4.6e-16)
+
+Indeed, the keys generated by symbol are automatically detected by the
+***print*** method in the ***Values*** class, and rendered in
+human-readable form “x1”, “l2”, etc, rather than as large, unwieldy
+integers. This magic extends to most factors and other classes where the
+**Key** type is used.
+
+A Larger Example
+~~~~~~~~~~~~~~~~~~~~
+
+|image: 14\_Users\_dellaert\_git\_github\_doc\_images\_littleRobot.png|
+Figure 12: A larger example with about 100 poses and 30 or so landmarks,
+as produced by gtsam\_examples/PlanarSLAMExample\_graph.m
+
+GTSAM comes with a slightly larger example that is read from a .graph
+file by PlanarSLAMExample\_graph.m, shown in Figure
+`12 <#fig_littleRobot>`__. To not clutter the figure only the marginals
+are shown, not the lines of sight. This example, with 119 (multivariate)
+variables and 517 factors optimizes in less than 10 ms.
+
+A Real-World Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+|image: 15\_Users\_dellaert\_git\_github\_doc\_images\_Victoria.png|
+Figure 13: Small section of optimized trajectory and landmarks (trees
+detected in a laser range finder scan) from data recorded in Sydney's
+Victoria Park (dataset due to Jose Guivant, U. Sydney).
+
+A real-world example is shown in Figure `13 <#fig_Victoria_1>`__, using
+data from a well known dataset collected in Sydney's Victoria Park,
+using a truck equipped with a laser range-finder. The covariance
+matrices in this figure were computed very efficiently, as explained in
+detail in (`Kaess and Dellaert, 2009 <#LyXCite-Kaess09ras>`__). The
+exact covariances (blue, smaller ellipses) obtained by our fast
+algorithm coincide with the exact covariances based on full inversion
+(orange, mostly hidden by blue). The much larger conservative covariance
+estimates (green, large ellipses) were based on our earlier work in
+(`Kaess et al., 2008 <#LyXCite-Kaess08tro>`__).

docs/source/MatlabExamples.rst

@@ -0,0 +1,5 @@
+Matlab Examples
+=================
+
+
+(Some selected examples from source code.)