Merge pull request #2049 from borglab/update-wrap

Wrap Update

wrap/.github/workflows/linux-ci.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - name: Checkout

wrap/.github/workflows/macos-ci.yml

@@ -5,12 +5,12 @@ on: [pull_request]
 jobs:
   build:
     name: Tests for 🐍 ${{ matrix.python-version }}
-    runs-on: macos-12
+    runs-on: macos-14
 
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - name: Checkout

wrap/CMakeLists.txt

@@ -20,6 +20,8 @@ set(INSTALL_LIB_DIR lib/${PROJECT_NAME})
 set(INSTALL_BIN_DIR bin/${PROJECT_NAME})
 set(INSTALL_INCLUDE_DIR include/${PROJECT_NAME})
 
+option(GTWRAP_ADD_DOCSTRINGS "Whether to add docstrings to the Python bindings from Doxygen-generated XML located at {project_root}/xml" OFF)
+
 # ##############################################################################
 # Package Configuration
 

wrap/cmake/PybindWrap.cmake

@@ -13,6 +13,14 @@ gtwrap_get_python_version(${WRAP_PYTHON_VERSION})
 message(STATUS "Setting Python version for wrapper")
 set(PYBIND11_PYTHON_VERSION ${WRAP_PYTHON_VERSION})
 
+if(GTWRAP_ADD_DOCSTRINGS)
+  set(GTWRAP_PYTHON_DOCS_SOURCE "${CMAKE_SOURCE_DIR}/xml")
+  message(STATUS "Python docstring generation is on. XML source: '${GTWRAP_PYTHON_DOCS_SOURCE}'")
+else()
+  message(STATUS "Python docstring generation is off.")
+  set(GTWRAP_PYTHON_DOCS_SOURCE "")
+endif()
+
 # User-friendly Pybind11 wrapping and installing function. Builds a Pybind11
 # module from the provided interface_headers. For example, for the interface
 # header gtsam.h, this will build the wrap module 'gtsam_py.cc'.
@@ -82,6 +90,7 @@ function(
           --out "${cpp_file}"  --module_name ${module_name}
           --top_module_namespaces "${top_namespace}" --ignore ${ignore_classes}
           --template ${module_template} --is_submodule ${_WRAP_BOOST_ARG}
+          --xml_source "${GTWRAP_PYTHON_DOCS_SOURCE}"
       DEPENDS "${interface_file}" ${module_template} "${module_name}/specializations/${interface}.h" "${module_name}/preamble/${interface}.h"
       VERBATIM)
 
@@ -100,6 +109,7 @@ function(
       --out "${generated_cpp}" --module_name ${module_name}
       --top_module_namespaces "${top_namespace}" --ignore ${ignore_classes}
       --template ${module_template} ${_WRAP_BOOST_ARG}
+      --xml_source "${GTWRAP_PYTHON_DOCS_SOURCE}"
     DEPENDS "${main_interface}" ${module_template} "${module_name}/specializations/${main_interface_name}.h" "${module_name}/specializations/${main_interface_name}.h"
     VERBATIM)
 

wrap/gtwrap/pybind_wrapper.py

@@ -19,6 +19,7 @@
 import gtwrap.interface_parser as parser
 import gtwrap.template_instantiator as instantiator
 
+from gtwrap.xml_parser.xml_parser import XMLDocParser
 
 class PybindWrapper:
     """
@@ -29,8 +30,9 @@ def __init__(self,
                  module_name,
                  top_module_namespaces='',
                  use_boost_serialization=False,
-                 ignore_classes=(),
-                 module_template=""):
+                 ignore_classes=(),                 
+                 module_template="",
+                 xml_source=""):
         self.module_name = module_name
         self.top_module_namespaces = top_module_namespaces
         self.use_boost_serialization = use_boost_serialization
@@ -44,6 +46,8 @@ def __init__(self,
             'nonlocal', 'yield', 'break', 'for', 'not', 'class', 'from', 'or',
             'continue', 'global', 'pass'
         ]
+        self.xml_source = xml_source
+        self.xml_parser = XMLDocParser()
 
         self.dunder_methods = ('len', 'contains', 'iter')
 
@@ -260,7 +264,7 @@ def _wrap_method(self,
                '[]({opt_self}{opt_comma}{args_signature_with_names}){{'
                '{function_call}'
                '}}'
-               '{py_args_names}){suffix}'.format(
+               '{py_args_names}{docstring}){suffix}'.format(
                    prefix=prefix,
                    cdef="def_static" if is_static else "def",
                    py_method=py_method,
@@ -271,6 +275,12 @@ def _wrap_method(self,
                    function_call=function_call,
                    py_args_names=py_args_names,
                    suffix=suffix,
+                   # Try to get the function's docstring from the Doxygen XML.
+                   # If extract_docstring errors or fails to find a docstring, it just prints a warning.
+                   # The incantation repr(...)[1:-1].replace('"', r'\"') replaces newlines with \n 
+                   # and " with \" so that the docstring can be put into a C++ string on a single line.
+                   docstring=', "' + repr(self.xml_parser.extract_docstring(self.xml_source, cpp_class, cpp_method, method.args.names()))[1:-1].replace('"', r'\"') + '"' 
+                       if self.xml_source != "" else "",
                ))
 
         # Create __repr__ override