Fix Python parameter docs (#537)

Also fixed most stubgen warnings by delaying method binding to after
class creation.

cmake/fix_stubgen.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+
+"""
+Fixes errors in .pyi files generated by stubgen.
+"""
+
+import re
+import os
+import sys
+
+
+def main():
+    # sys.argv[1] should be a directory in which to search for .pyi files
+    filenames = [
+        os.path.join(dp, f)
+        for dp, dn, fn in os.walk(sys.argv[1])
+        for f in fn
+        if f.endswith(".pyi")
+    ]
+    for filename in filenames:
+        with open(filename) as f:
+            content = f.read()
+
+        # Fix errors
+        content = content.replace(
+            "<ExpressionType.NONE: 0>", "ExpressionType.NONE"
+        ).replace("<SolverExitCondition.SUCCESS: 0>", "SolverExitCondition.SUCCESS")
+
+        # Convert parameter names from camel case to snake case
+        new_content = ""
+        extract_location = 0
+        for match in re.finditer(r"(?<=Parameter ``)(.*?)(?=``:)", content):
+            new_content += content[extract_location : match.start()]
+            new_content += re.sub(r"(?<!^)(?=[A-Z])", "_", match.group()).lower()
+            extract_location = match.end()
+        content = new_content + content[extract_location:]
+
+        with open(filename, mode="w") as f:
+            f.write(content)
+
+
+if __name__ == "__main__":
+    main()

cmake/modules/Pybind11Stubgen.cmake

@@ -8,6 +8,10 @@ function(pybind11_stubgen target)
             --print-invalid-expressions-as-is --exit-code
             $<TARGET_FILE_BASE_NAME:${target}> -o
             $<TARGET_FILE_DIR:${target}>-stubs
+        COMMAND
+            ${Python3_EXECUTABLE}
+            ${CMAKE_CURRENT_SOURCE_DIR}/cmake/fix_stubgen.py
+            $<TARGET_FILE_DIR:${target}>-stubs
         WORKING_DIRECTORY $<TARGET_FILE_DIR:${target}>
         USES_TERMINAL
     )

include/sleipnir/autodiff/VariableBlock.hpp

@@ -26,6 +26,8 @@ class VariableBlock {
 
   /**
    * Assigns a VariableBlock to the block.
+   *
+   * @param values VariableBlock of values.
    */
   VariableBlock<Mat>& operator=(const VariableBlock<Mat>& values) {
     if (this == &values) {
@@ -56,6 +58,8 @@ class VariableBlock {
 
   /**
    * Assigns a VariableBlock to the block.
+   *
+   * @param values VariableBlock of values.
    */
   VariableBlock<Mat>& operator=(VariableBlock<Mat>&& values) {
     if (this == &values) {
@@ -124,6 +128,8 @@ class VariableBlock {
    * Assigns a double to the block.
    *
    * This only works for blocks with one row and one column.
+   *
+   * @param value Value to assign.
    */
   VariableBlock<Mat>& SetValue(double value) {
     Assert(Rows() == 1 && Cols() == 1);
@@ -135,6 +141,8 @@ class VariableBlock {
 
   /**
    * Assigns an Eigen matrix to the block.
+   *
+   * @param values Eigen matrix of values to assign.
    */
   template <typename Derived>
   VariableBlock<Mat>& operator=(const Eigen::MatrixBase<Derived>& values) {
@@ -152,6 +160,8 @@ class VariableBlock {
 
   /**
    * Sets block's internal values.
+   *
+   * @param values Eigen matrix of values.
    */
   template <typename Derived>
     requires std::same_as<typename Derived::Scalar, double>
@@ -170,6 +180,8 @@ class VariableBlock {
 
   /**
    * Assigns a VariableMatrix to the block.
+   *
+   * @param values VariableMatrix of values.
    */
   VariableBlock<Mat>& operator=(const Mat& values) {
     Assert(Rows() == values.Rows());
@@ -185,6 +197,8 @@ class VariableBlock {
 
   /**
    * Assigns a VariableMatrix to the block.
+   *
+   * @param values VariableMatrix of values.
    */
   VariableBlock<Mat>& operator=(Mat&& values) {
     Assert(Rows() == values.Rows());

include/sleipnir/autodiff/VariableMatrix.hpp

@@ -137,6 +137,8 @@ class SLEIPNIR_DLLEXPORT VariableMatrix {
 
   /**
    * Constructs a VariableMatrix from an Eigen matrix.
+   *
+   * @param values Eigen matrix of values.
    */
   template <typename Derived>
   VariableMatrix(const Eigen::MatrixBase<Derived>& values)  // NOLINT
@@ -152,6 +154,8 @@ class SLEIPNIR_DLLEXPORT VariableMatrix {
 
   /**
    * Constructs a VariableMatrix from an Eigen diagonal matrix.
+   *
+   * @param values Diagonal matrix of values.
    */
   template <typename Derived>
   VariableMatrix(const Eigen::DiagonalBase<Derived>& values)  // NOLINT
@@ -171,6 +175,8 @@ class SLEIPNIR_DLLEXPORT VariableMatrix {
 
   /**
    * Assigns an Eigen matrix to a VariableMatrix.
+   *
+   * @param values Eigen matrix of values.
    */
   template <typename Derived>
   VariableMatrix& operator=(const Eigen::MatrixBase<Derived>& values) {
@@ -188,6 +194,8 @@ class SLEIPNIR_DLLEXPORT VariableMatrix {
 
   /**
    * Sets the VariableMatrix's internal values.
+   *
+   * @param values Eigen matrix of values.
    */
   template <typename Derived>
     requires std::same_as<typename Derived::Scalar, double>
@@ -206,6 +214,8 @@ class SLEIPNIR_DLLEXPORT VariableMatrix {
 
   /**
    * Constructs a scalar VariableMatrix from a Variable.
+   *
+   * @param variable Variable.
    */
   VariableMatrix(const Variable& variable)  // NOLINT
       : m_rows{1}, m_cols{1} {
@@ -214,13 +224,17 @@ class SLEIPNIR_DLLEXPORT VariableMatrix {
 
   /**
    * Constructs a scalar VariableMatrix from a Variable.
+   *
+   * @param variable Variable.
    */
   VariableMatrix(Variable&& variable) : m_rows{1}, m_cols{1} {  // NOLINT
     m_storage.emplace_back(std::move(variable));
   }
 
   /**
    * Constructs a VariableMatrix from a VariableBlock.
+   *
+   * @param values VariableBlock of values.
    */
   VariableMatrix(const VariableBlock<VariableMatrix>& values)  // NOLINT
       : m_rows{values.Rows()}, m_cols{values.Cols()} {
@@ -233,6 +247,8 @@ class SLEIPNIR_DLLEXPORT VariableMatrix {
 
   /**
    * Constructs a VariableMatrix from a VariableBlock.
+   *
+   * @param values VariableBlock of values.
    */
   VariableMatrix(const VariableBlock<const VariableMatrix>& values)  // NOLINT
       : m_rows{values.Rows()}, m_cols{values.Cols()} {

jormungandr/cpp/Binders.hpp

@@ -3,23 +3,41 @@
 #pragma once
 
 #include <pybind11/pybind11.h>
+#include <sleipnir/autodiff/ExpressionType.hpp>
+#include <sleipnir/autodiff/Gradient.hpp>
+#include <sleipnir/autodiff/Hessian.hpp>
+#include <sleipnir/autodiff/Jacobian.hpp>
+#include <sleipnir/autodiff/Variable.hpp>
+#include <sleipnir/autodiff/VariableBlock.hpp>
+#include <sleipnir/autodiff/VariableMatrix.hpp>
+#include <sleipnir/optimization/Constraints.hpp>
+#include <sleipnir/optimization/OptimizationProblem.hpp>
+#include <sleipnir/optimization/SolverExitCondition.hpp>
+#include <sleipnir/optimization/SolverIterationInfo.hpp>
+#include <sleipnir/optimization/SolverStatus.hpp>
 
 namespace py = pybind11;
 
 namespace sleipnir {
 
-void BindExpressionType(py::module_& autodiff);
-void BindGradient(py::module_& autodiff);
-void BindHessian(py::module_& autodiff);
-void BindJacobian(py::module_& autodiff);
-void BindVariable(py::module_& autodiff);
-void BindVariableBlock(py::module_& autodiff);
-void BindVariableMatrix(py::module_& autodiff);
-
-void BindConstraints(py::module_& optimization);
-void BindOptimizationProblem(py::module_& optimization);
-void BindSolverExitCondition(py::module_& optimization);
-void BindSolverIterationInfo(py::module_& optimization);
-void BindSolverStatus(py::module_& optimization);
+void BindExpressionType(py::enum_<ExpressionType>& e);
+
+void BindVariable(py::module_& autodiff, py::class_<Variable>& cls);
+void BindVariableMatrix(py::module_& autodiff, py::class_<VariableMatrix>& cls);
+void BindVariableBlock(py::module_& autodiff,
+                       py::class_<VariableBlock<VariableMatrix>>& cls);
+
+void BindGradient(py::class_<Gradient>& cls);
+void BindHessian(py::class_<Hessian>& cls);
+void BindJacobian(py::class_<Jacobian>& cls);
+
+void BindEqualityConstraints(py::class_<EqualityConstraints>& cls);
+void BindInequalityConstraints(py::class_<InequalityConstraints>& cls);
+
+void BindSolverExitCondition(py::enum_<SolverExitCondition>& e);
+void BindSolverIterationInfo(py::class_<SolverIterationInfo>& cls);
+void BindSolverStatus(py::class_<SolverStatus>& cls);
+
+void BindOptimizationProblem(py::class_<OptimizationProblem>& cls);
 
 }  // namespace sleipnir

jormungandr/cpp/Docstrings.hpp

@@ -1085,9 +1085,16 @@ static const char *__doc_sleipnir_VariableBlock_Rows = R"doc(Returns number of r
 static const char *__doc_sleipnir_VariableBlock_SetValue =
 R"doc(Assigns a double to the block.
 
-This only works for blocks with one row and one column.)doc";
+This only works for blocks with one row and one column.
+
+Parameter ``value``:
+    Value to assign.)doc";
+
+static const char *__doc_sleipnir_VariableBlock_SetValue_2 =
+R"doc(Sets block's internal values.
 
-static const char *__doc_sleipnir_VariableBlock_SetValue_2 = R"doc(Sets block's internal values.)doc";
+Parameter ``values``:
+    Eigen matrix of values.)doc";
 
 static const char *__doc_sleipnir_VariableBlock_T = R"doc(Returns the transpose of the variable matrix.)doc";
 
@@ -1194,20 +1201,40 @@ static const char *__doc_sleipnir_VariableBlock_m_mat = R"doc()doc";
 
 static const char *__doc_sleipnir_VariableBlock_m_rowOffset = R"doc()doc";
 
-static const char *__doc_sleipnir_VariableBlock_operator_assign = R"doc(Assigns a VariableBlock to the block.)doc";
+static const char *__doc_sleipnir_VariableBlock_operator_assign =
+R"doc(Assigns a VariableBlock to the block.
+
+Parameter ``values``:
+    VariableBlock of values.)doc";
+
+static const char *__doc_sleipnir_VariableBlock_operator_assign_2 =
+R"doc(Assigns a VariableBlock to the block.
 
-static const char *__doc_sleipnir_VariableBlock_operator_assign_2 = R"doc(Assigns a VariableBlock to the block.)doc";
+Parameter ``values``:
+    VariableBlock of values.)doc";
 
 static const char *__doc_sleipnir_VariableBlock_operator_assign_3 =
 R"doc(Assigns a double to the block.
 
 This only works for blocks with one row and one column.)doc";
 
-static const char *__doc_sleipnir_VariableBlock_operator_assign_4 = R"doc(Assigns an Eigen matrix to the block.)doc";
+static const char *__doc_sleipnir_VariableBlock_operator_assign_4 =
+R"doc(Assigns an Eigen matrix to the block.
+
+Parameter ``values``:
+    Eigen matrix of values to assign.)doc";
+
+static const char *__doc_sleipnir_VariableBlock_operator_assign_5 =
+R"doc(Assigns a VariableMatrix to the block.
 
-static const char *__doc_sleipnir_VariableBlock_operator_assign_5 = R"doc(Assigns a VariableMatrix to the block.)doc";
+Parameter ``values``:
+    VariableMatrix of values.)doc";
+
+static const char *__doc_sleipnir_VariableBlock_operator_assign_6 =
+R"doc(Assigns a VariableMatrix to the block.
 
-static const char *__doc_sleipnir_VariableBlock_operator_assign_6 = R"doc(Assigns a VariableMatrix to the block.)doc";
+Parameter ``values``:
+    VariableMatrix of values.)doc";
 
 static const char *__doc_sleipnir_VariableBlock_operator_call =
 R"doc(Returns a scalar subblock at the given row and column.
@@ -1373,7 +1400,11 @@ Parameter ``offset``:
 Parameter ``length``:
     The length of the segment.)doc";
 
-static const char *__doc_sleipnir_VariableMatrix_SetValue = R"doc(Sets the VariableMatrix's internal values.)doc";
+static const char *__doc_sleipnir_VariableMatrix_SetValue =
+R"doc(Sets the VariableMatrix's internal values.
+
+Parameter ``values``:
+    Eigen matrix of values.)doc";
 
 static const char *__doc_sleipnir_VariableMatrix_T = R"doc(Returns the transpose of the variable matrix.)doc";
 
@@ -1433,17 +1464,41 @@ This overload is for Python bindings only.
 Parameter ``list``:
     The nested list of Variables.)doc";
 
-static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_7 = R"doc(Constructs a VariableMatrix from an Eigen matrix.)doc";
+static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_7 =
+R"doc(Constructs a VariableMatrix from an Eigen matrix.
+
+Parameter ``values``:
+    Eigen matrix of values.)doc";
+
+static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_8 =
+R"doc(Constructs a VariableMatrix from an Eigen diagonal matrix.
 
-static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_8 = R"doc(Constructs a VariableMatrix from an Eigen diagonal matrix.)doc";
+Parameter ``values``:
+    Diagonal matrix of values.)doc";
+
+static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_9 =
+R"doc(Constructs a scalar VariableMatrix from a Variable.
 
-static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_9 = R"doc(Constructs a scalar VariableMatrix from a Variable.)doc";
+Parameter ``variable``:
+    Variable.)doc";
 
-static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_10 = R"doc(Constructs a scalar VariableMatrix from a Variable.)doc";
+static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_10 =
+R"doc(Constructs a scalar VariableMatrix from a Variable.
 
-static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_11 = R"doc(Constructs a VariableMatrix from a VariableBlock.)doc";
+Parameter ``variable``:
+    Variable.)doc";
 
-static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_12 = R"doc(Constructs a VariableMatrix from a VariableBlock.)doc";
+static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_11 =
+R"doc(Constructs a VariableMatrix from a VariableBlock.
+
+Parameter ``values``:
+    VariableBlock of values.)doc";
+
+static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_12 =
+R"doc(Constructs a VariableMatrix from a VariableBlock.
+
+Parameter ``values``:
+    VariableBlock of values.)doc";
 
 static const char *__doc_sleipnir_VariableMatrix_VariableMatrix_13 =
 R"doc(Constructs a column vector wrapper around a Variable array.
@@ -1528,7 +1583,11 @@ static const char *__doc_sleipnir_VariableMatrix_m_storage = R"doc()doc";
 
 static const char *__doc_sleipnir_VariableMatrix_operator_Variable = R"doc(Implicit conversion operator from 1x1 VariableMatrix to Variable.)doc";
 
-static const char *__doc_sleipnir_VariableMatrix_operator_assign = R"doc(Assigns an Eigen matrix to a VariableMatrix.)doc";
+static const char *__doc_sleipnir_VariableMatrix_operator_assign =
+R"doc(Assigns an Eigen matrix to a VariableMatrix.
+
+Parameter ``values``:
+    Eigen matrix of values.)doc";
 
 static const char *__doc_sleipnir_VariableMatrix_operator_call =
 R"doc(Returns a block pointing to the given row and column.