Replace pybind11 dartpy with nanobind (#2249)

Author: jslee02

.gitignore

@@ -59,6 +59,7 @@ docs/doxygen/html/
 docs/readthedocs/site
 docs/readthedocs/_build/
 docs/readthedocs/_generated/
+docs/readthedocs/_generated_stubs/
 docs/python_api/_build/
 
 # Data files

Brewfile

@@ -37,4 +37,3 @@ brew 'urdfdom'
 
 # dartpy dependencies
 brew 'python3'
-brew 'pybind11'

CMakeLists.txt

@@ -247,7 +247,7 @@ dart_option(DART_USE_SYSTEM_IMGUI
   "Use system-installed ImGui instead of fetching from GitHub (recommended for package distributions)" OFF CATEGORY system)
 dart_option(DART_USE_SYSTEM_GOOGLEBENCHMARK "Use system GoogleBenchmark" OFF CATEGORY system)
 dart_option(DART_USE_SYSTEM_GOOGLETEST "Use system GoogleTest" OFF CATEGORY system)
-dart_option(DART_USE_SYSTEM_PYBIND11 "Use system pybind11" OFF CATEGORY system)
+dart_option(DART_USE_SYSTEM_NANOBIND "Use system nanobind" OFF CATEGORY system)
 dart_option(DART_USE_SYSTEM_TRACY "Use system Tracy" OFF CATEGORY system)
 dart_option(DART_VERBOSE "Whether print detailed information in CMake process" OFF CATEGORY diagnostics)
 dart_option(DART_BUILD_DART8 "Build experimental DART8 library" OFF CATEGORY build)
@@ -674,7 +674,10 @@ endif()
 add_subdirectory(python)
 
 # Add 'ALL' target that builds everything
-set(all_target_candidates dartpy)
+set(all_target_candidates)
+if(DART_BUILD_DARTPY)
+  list(APPEND all_target_candidates dartpy)
+endif()
 if(DART_BUILD_TESTS AND BUILD_TESTING)
   list(APPEND all_target_candidates tests_and_run pytest)
 endif()
@@ -1003,8 +1006,7 @@ message(STATUS "Run '${DART_CMAKE_BUILD_CMD} --target tutorials' to build all th
 message(STATUS "Run '${DART_CMAKE_BUILD_CMD} --target view_docs' to see the API documentation")
 message(STATUS "Run '${DART_CMAKE_BUILD_CMD} --target install' to install all the C++ components")
 if(TARGET dartpy)
-  message(STATUS "Run '${DART_CMAKE_BUILD_CMD} --target dartpy' to build dartpy")
-  message(STATUS "Run '${DART_CMAKE_BUILD_CMD} --target install' to install dartpy")
+  message(STATUS "Run '${DART_CMAKE_BUILD_CMD} --target dartpy' to build the python bindings")
 endif()
 if(TARGET coverage)
   message(STATUS "- 'coverage'     : generate coverage report")

docker/dev/v6.16/Dockerfile.ubuntu.jammy

@@ -55,15 +55,14 @@ RUN apt-get install -y --no-install-recommends \
 
 RUN apt-get install -y --no-install-recommends \
     libpython3-dev \
-    pybind11-dev \
     python3 \
     python3-dev \
     python3-distutils \
     python3-numpy \
     python3-pip \
     python3-setuptools
 
-RUN pip3 install pytest -U
+RUN pip3 install --no-cache-dir nanobind pytest -U
 
 # ==============================================================================
 # Clean up

docker/dev/v6.16/Dockerfile.ubuntu.noble

@@ -55,14 +55,15 @@ RUN apt-get install -y --no-install-recommends \
 
 RUN apt-get install -y --no-install-recommends \
     libpython3-dev \
-    pybind11-dev \
     python3 \
     python3-dev \
     python3-numpy \
     python3-pip \
     python3-pytest \
     python3-setuptools
 
+RUN pip3 install --no-cache-dir nanobind pytest -U
+
 # ==============================================================================
 # Clean up
 # ==============================================================================

docker/dev/v6.16/Dockerfile.ubuntu.plucky

@@ -55,14 +55,15 @@ RUN apt-get install -y --no-install-recommends \
 
 RUN apt-get install -y --no-install-recommends \
     libpython3-dev \
-    pybind11-dev \
     python3 \
     python3-dev \
     python3-numpy \
     python3-pip \
     python3-pytest \
     python3-setuptools
 
+RUN pip3 install --no-cache-dir nanobind pytest -U
+
 # ==============================================================================
 # Clean up
 # ==============================================================================

docker/dev/v6.16/Dockerfile.ubuntu.questing

@@ -55,14 +55,15 @@ RUN apt-get install -y --no-install-recommends \
 
 RUN apt-get install -y --no-install-recommends \
     libpython3-dev \
-    pybind11-dev \
     python3 \
     python3-dev \
     python3-numpy \
     python3-pip \
     python3-pytest \
     python3-setuptools
 
+RUN pip3 install --no-cache-dir nanobind pytest -U
+
 # ==============================================================================
 # Clean up
 # ==============================================================================

docs/readthedocs/README.md

@@ -43,7 +43,7 @@ pixi run docs-serve-ko
 
 ### How It Works
 
-The Python API documentation is generated using Sphinx autodoc, which requires the `dartpy` module to be importable.
+The Python API documentation is generated using Sphinx autodoc, which requires the `dartpy` module (nanobind extension) to be importable.
 
 **Local builds:**
 
@@ -53,9 +53,8 @@ The Python API documentation is generated using Sphinx autodoc, which requires t
 
 **Read the Docs builds:**
 
-- dartpy is a C++ extension built with pybind11 and cannot be compiled on Read the Docs
-- API documentation pages will be empty until we implement pre-built wheels
-- The documentation structure and navigation will still work correctly
+- Read the Docs cannot compile the C++ extension, so `conf.py` falls back to generated stubs under `python/stubs/dartpy`.
+- If compatible wheels are available for RTD’s image, the requirements file pins one so autodoc can use the real module; otherwise the stubs keep the API pages rendering.
 
 ### Generating Stub Files
 
@@ -91,14 +90,10 @@ The `docs-build` task:
 
 ### Read the Docs ✅
 
-Read the Docs now installs `dartpy` prior to running Sphinx so the Python API pages
-render there as well. RTD's Ubuntu 22.04 images are still on glibc 2.35, so the
-requirements file pins `dartpy==6.16.0`, the last release whose wheels remain compatible
-with glibc 2.27. That wheel set only targets CPython 3.12+ (cp312–cp314), so `.readthedocs.yml`
-now pins the RTD runtime to Python 3.12. Local builds can continue using the
-`pip install --pre dartpy` flow for the bleeding-edge bindings. Once RTD upgrades
-(or we ship compatible wheels), update `docs/readthedocs/requirements.txt` and
-`.readthedocs.yml` to match and remove these temporary pins.
+Read the Docs currently relies on prebuilt `dartpy` wheels when they match the RTD
+image; otherwise it uses the shipped stubs. The requirements pin may change as RTD
+images and wheel compatibility evolve—adjust `docs/readthedocs/requirements.txt` and
+`.readthedocs.yml` when newer wheels are usable so autodoc can introspect the live module.
 
 ### Future: keep wheels fresh 🎯
 

docs/readthedocs/conf.py

@@ -169,7 +169,6 @@ def _render_doxyfile(output_path: Path):
 
     output_path.write_text(doxyfile_contents)
 
-
 def _read_dart_semver():
     """Return the DART semantic version as read from package.xml."""
     import xml.etree.ElementTree as ET
@@ -194,14 +193,44 @@ def get_dart_version(prefix_with_v: bool = True):
     return f"v{semver}" if prefix_with_v else semver
 
 
+def _read_api_versions():
+    """Return the list of published documentation versions."""
+
+    versions_file = REPO_ROOT / "scripts" / "docs_versions.txt"
+    versions = []
+    try:
+        for line in versions_file.read_text().splitlines():
+            line = line.strip()
+            if line and not line.startswith("DART "):
+                versions.append(line)
+    except FileNotFoundError:
+        # Fallback to a safe default when running locally without the helper.
+        versions = ["v6.16.0"]
+    return versions
+
+
 # Get current DART version from package.xml
 current_version = get_dart_version()
+api_versions = _read_api_versions()
+if current_version in api_versions:
+    api_version_to_link = current_version
+else:
+    api_version_to_link = api_versions[0] if api_versions else current_version
 
-# Make these available to RST files via html_context
 html_context = {
     "current_version": current_version,
+    "api_versions": api_versions,
+    "api_version_to_link": api_version_to_link,
+    "cpp_api_url": f"https://dartsim.github.io/dart/{api_version_to_link}/",
+    "python_api_url": f"https://dartsim.github.io/dart/{api_version_to_link}-py/",
+    "gh_pages_url": "https://github.com/dartsim/dart/tree/gh-pages",
 }
 
+# Provide easy-to-reuse substitutions in the RST files.
+rst_epilog = f"""
+.. |python_api_url| replace:: {html_context['python_api_url']}
+"""
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -254,7 +283,13 @@ def get_dart_version(prefix_with_v: bool = True):
 # The master toctree document.
 root_doc = "index"
 
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "README.md",
+    "dartpy/api/*",
+]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -283,7 +318,6 @@ def get_dart_version(prefix_with_v: bool = True):
     """
 }
 
-
 def build_cpp_api_docs(app):
     """Generate the Doxygen HTML bundle so RTD serves versioned C++ docs."""
 

docs/readthedocs/dartpy/python_api_reference.rst

@@ -1,19 +1,16 @@
 Python API Reference
-=====================
+====================
 
-The full dartpy API reference now builds directly on Read the Docs, so you no
-longer need to leave the site or rely on a separate GitHub Pages deployment.
-This page renders the documentation straight from the published ``dartpy``
-wheel, which means the members, signatures, and type hints always match the
-latest PyPI release.
+The full ``dartpy`` API reference is built directly on Read the Docs using the
+wheel pinned in ``docs/readthedocs/requirements.txt``. Sphinx imports the
+modules under ``docs/python_api/`` and auto-documents them using the installed
+package. Local builds use the compiled extension in ``build/.../python`` so the
+API pages always reflect the current nanobind bindings.
 
-.. admonition:: How these docs are generated
-
-   * RTD installs the ``dartpy`` wheel listed in :file:`docs/readthedocs/requirements.txt`.
-   * Sphinx loads the modules under :file:`docs/python_api/` and auto-documents
-     them using the installed package.
-   * Local builds can use ``pixi run docs-build`` or ``pixi run api-docs-py``
-     for the same result.
+.. note::
+   If a compatible wheel is unavailable, ``conf.py`` falls back to the stub
+   package in ``python/stubs/dartpy`` so RTD still renders the module layout.
+   Local builds can always use ``pixi run docs-build`` or ``pixi run api-docs-py``.
 
 Getting Started
 ---------------
@@ -29,28 +26,17 @@ To explore the bindings locally:
    print(world.getGravity())
    PY
 
-The sections below mirror the module layout from :file:`docs/python_api/`.
-
 Module Reference
 ----------------
 
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   /dartpy/api/modules/common
-   /dartpy/api/modules/math
-   /dartpy/api/modules/dynamics
-   /dartpy/api/modules/simulation
-   /dartpy/api/modules/collision
-   /dartpy/api/modules/constraint
-   /dartpy/api/modules/optimizer
-   /dartpy/api/modules/utils
-   /dartpy/api/modules/gui
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+The sections below mirror the module layout from ``docs/python_api/``.
+
+* :doc:`dartpy.common <modules/common>`
+* :doc:`dartpy.math <modules/math>`
+* :doc:`dartpy.dynamics <modules/dynamics>`
+* :doc:`dartpy.simulation <modules/simulation>`
+* :doc:`dartpy.collision <modules/collision>`
+* :doc:`dartpy.constraint <modules/constraint>`
+* :doc:`dartpy.optimizer <modules/optimizer>`
+* :doc:`dartpy.utils <modules/utils>`
+* :doc:`dartpy.gui <modules/gui>`