Initial documentation

.gitignore

@@ -14,6 +14,10 @@ cmake-*/
 __pycache__/
 *.pyc
 
+### Documentation build artifacts
+docs/_build/
+docs/_doxygen/
+
 
 ### Standard C++ ignores
 # Prerequisites

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# ReadTheDocs build configuration.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  apt_packages:
+    - doxygen
+    - cmake
+  jobs:
+    # Generate the C++ XML that Breathe consumes, before Sphinx runs.
+    pre_build:
+      - doxygen docs/Doxyfile
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    # Sphinx + extensions.
+    - requirements: docs/requirements.txt
+    # Compile and install the `blast` extension so Python autodoc can import it.
+    - method: pip
+      path: .

blast/blast_optimization.hpp

@@ -102,7 +102,7 @@ struct ConstraintSelection {
 };
 
 struct Optimization {
-  OptimizationMethod  method;
+  OptimizationMethod  method = OptimizationMethod::with_segments;
   Manipulator         manip;
   Bspline             bspline;
   Guess               guess;
@@ -111,7 +111,7 @@ struct Optimization {
   Matrix              task;
   World               world;
   real                trajectory_start_time = 0.0;
-  real                success_tolerance     = 0.0;  // % of constraint violation after optimization that is still considered a success
+  real                success_tolerance     = 0.01; // constraint violation after optimization that is still considered a success
   int                 max_tries             = 1;    // Maximum number of tries in the optimization loop.
   int                 max_eval              = 1000; // Maximum number of function evaluations for a single NLopt call.
   real                max_time              = 30.0; // Maximum time (seconds) for a single NLopt call.
@@ -156,7 +156,6 @@ inline void nlopt_constraints_with_analytical_dynamics(unsigned m, double* resul
 
 // inline real   bound_constraint(const real& value, const real& value_min, const real& value_max);
 // inline Matrix get_J_tool(const Optimization* opt);
-// inline bool   validate_task(Optimization* opt);
 } // namespace blast
 
 #include "optimization/constraints.hpp"

docs/Doxyfile

@@ -0,0 +1,45 @@
+# Doxygen configuration for Blast — emits XML only, consumed by Breathe/Sphinx.
+#
+# Run from the repository root:
+#     doxygen docs/Doxyfile
+#
+# Output lands in docs/_doxygen/xml, which conf.py's breathe_projects points at.
+# Only non-default tags are listed; Doxygen supplies defaults for the rest.
+
+PROJECT_NAME           = "Blast"
+PROJECT_BRIEF          = "Fast C++ trajectory optimization for robot manipulators"
+
+# Inputs (paths are relative to the working directory = repo root).
+INPUT                  = blast
+FILE_PATTERNS          = *.hpp *.h
+RECURSIVE              = YES
+EXCLUDE                = blast/extern
+
+# We only want machine-readable XML for Breathe.
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+OUTPUT_DIRECTORY       = docs/_doxygen
+XML_OUTPUT             = xml
+
+# Extraction: surface everything so undocumented members still appear,
+# and pick up plain // comments as brief descriptions where present.
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = YES
+MULTILINE_CPP_IS_BRIEF = YES
+
+# Keep the macro-heavy header-only API readable.
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = "blast_fn=" \
+                         "host_fn=" \
+                         "device_fn=" \
+                         "__host__=" \
+                         "__device__=" \
+                         "PROFILE_SCOPE(x)=" \
+                         "PROFILE_FUNCTION="
+
+QUIET                  = YES
+WARN_IF_UNDOCUMENTED   = NO