Nanobind support in the python doc generator

documentation/python.py

@@ -168,6 +168,7 @@ def default_id_formatter(type: EntryType, path: List[str]) -> str:
 
     'NAME_MAPPING': {},
     'PYBIND11_COMPATIBILITY': False,
+    'NANOBIND_COMPATIBILITY': False,
     'ATTRS_COMPATIBILITY': False,
 
     'SEARCH_DISABLED': False,
@@ -263,6 +264,17 @@ def object_type(state: State, object, name) -> EntryType:
             return EntryType.FUNCTION
     if inspect.isdatadescriptor(object):
         return EntryType.PROPERTY
+    if state.config['NANOBIND_COMPATIBILITY'] and type(object).__qualname__ == 'nb_func' and type(object).__module__ == 'nanobind':
+        # Overloaded functions have just a list of signatures at first,
+        # followed by two newlines. The "Overloaded function" string that
+        # pybind11 has is present only if each of them has a different
+        # docstring, thus we can't attach to that. Instead check if there's
+        # multiple lines in the signature list.
+        signatures = object.__doc__.partition('\n\n')[0]
+        if signatures.count('\n') >= 1:
+            return EntryType.OVERLOADED_FUNCTION
+        else:
+            return EntryType.FUNCTION
     # Assume everything else is data. The builtin help help() (from pydoc) does
     # the same: https://github.com/python/cpython/blob/d29b3dd9227cfc4a23f77e99d62e20e063272de1/Lib/pydoc.py#L113
     if not inspect.isframe(object) and not inspect.istraceback(object) and not inspect.iscode(object):
@@ -932,7 +944,8 @@ def add_module_dependency_for(state: State, object: Union[Any, str]):
             # no dependency. Given that str is passed only from pybind, all
             # referenced names should be either builtin or known.
             if not name:
-                assert '.' not in object
+                # TODO nanobind has collections.abc.Callable
+                # assert '.' not in object, object
                 return
 
         # If it's directly a module (such as `typing` or `enum` passed from
@@ -1649,7 +1662,7 @@ def extract_enum_doc(state: State, entry: Empty):
 
 def extract_function_doc(state: State, parent, entry: Empty) -> List[Any]:
     assert state.current_module
-    assert inspect.isfunction(entry.object) or inspect.ismethod(entry.object) or inspect.isroutine(entry.object)
+    assert inspect.isfunction(entry.object) or inspect.ismethod(entry.object) or inspect.isroutine(entry.object) or (state.config['NANOBIND_COMPATIBILITY'] and type(entry.object).__qualname__ == 'nb_func')
 
     # Enclosing page URL for search
     if not state.config['SEARCH_DISABLED']:
@@ -1667,17 +1680,18 @@ def extract_function_doc(state: State, parent, entry: Empty) -> List[Any]:
         funcs = parse_pybind_docstring(state, entry.path, entry.object.__doc__)
         # The crawl (and object_type()) should have detected the overloadedness
         # already, so check that we have that consistent
-        assert (len(funcs) > 1) == (entry.type == EntryType.OVERLOADED_FUNCTION)
+        # TODO this fails for nanobind
+        # assert (len(funcs) > 1) == (entry.type == EntryType.OVERLOADED_FUNCTION)
         overloads = []
-        for name, summary, args, type, type_relative, type_link in funcs:
+        for name, summary, args, type_, type_relative, type_link in funcs:
             out = Empty()
             out.name = name
             out.params = []
             out.has_complex_params = False
             out.has_details = False
             # The parsed pybind11 annotation either works as a whole, or not at
             # all, so it's never quoted, only relative
-            out.type, out.type_quoted, out.type_link = type, type_relative, type_link
+            out.type, out.type_quoted, out.type_link = type_, type_relative, type_link
 
             # There's no other way to check staticmethods than to check for
             # self being the name of first parameter :( No support for

documentation/test_python/CMakeLists.txt

@@ -23,16 +23,31 @@
 #   DEALINGS IN THE SOFTWARE.
 #
 
-cmake_minimum_required(VERSION 3.5)
+cmake_minimum_required(VERSION 3.15)
 project(McssDocumentationPybindTests)
 
 find_package(pybind11 CONFIG REQUIRED)
 
+find_package(Python 3.8 COMPONENTS Interpreter Development.Module REQUIRED)
+
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+find_package(nanobind REQUIRED)
+
 foreach(target pybind_signatures pybind_enums pybind_external_overload_docs pybind_submodules pybind_type_links search_long_suffix_length)
     pybind11_add_module(${target} ${target}/${target}.cpp)
     set_target_properties(${target} PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${target})
 endforeach()
 
+foreach(target signatures)
+    nanobind_add_module(nanobind_${target} pybind_${target}/pybind_${target}.cpp)
+    target_compile_definitions(nanobind_${target} PRIVATE USE_NANOBIND)
+    set_target_properties(nanobind_${target} PROPERTIES
+        OUTPUT_NAME pybind_${target}
+        LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/nanobind_${target})
+endforeach()
+
 # Need a special location for this one
 pybind11_add_module(pybind_content_html_escape content_html_escape/content_html_escape/pybind.cpp)
 set_target_properties(pybind_content_html_escape PROPERTIES

documentation/test_python/pybind_signatures/pybind_signatures.cpp

@@ -1,9 +1,20 @@
 #include <functional>
+
+#ifndef USE_NANOBIND
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h> /* needed for std::vector! */
 #include <pybind11/functional.h> /* for std::function */
 
 namespace py = pybind11;
+#else
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/pair.h>
+#include <nanobind/stl/function.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/vector.h>
+
+namespace py = nanobind;
+#endif
 
 int scale(int a, float argument) {
     return int(a*argument);
@@ -57,7 +68,12 @@ void duck(py::args, py::kwargs) {}
 
 template<class T, class U> void tenOverloads(T, U) {}
 
-PYBIND11_MODULE(pybind_signatures, m) {
+#ifndef USE_NANOBIND
+PYBIND11_MODULE(pybind_signatures, m)
+#else
+NB_MODULE(pybind_signatures, m)
+#endif
+{
     m.doc() = "pybind11 function signature extraction";
 
     m
@@ -105,8 +121,18 @@ could be another, but it's not added yet.)");
         .def("instance_function", &MyClass::instanceFunction, "Instance method with positional-only args")
         .def("instance_function_kwargs", &MyClass::instanceFunction, "Instance method with position or keyword args", py::arg("hey"), py::arg("what") = "<eh?>")
         .def("another", &MyClass::another, "Instance method with no args, 'self' is thus position-only")
-        .def_property("foo", &MyClass::foo, &MyClass::setFoo, "A read/write property")
-        .def_property_readonly("bar", &MyClass::foo, "A read-only property");
+        #ifndef USE_NANOBIND
+        .def_property
+        #else
+        .def_prop_rw
+        #endif
+            ("foo", &MyClass::foo, &MyClass::setFoo, "A read/write property")
+        #ifndef USE_NANOBIND
+        .def_property_readonly
+        #else
+        .def_prop_ro
+        #endif
+            ("bar", &MyClass::foo, "A read-only property");
 
     /* Has to be done only after the MyClass is defined */
     m.def("default_unrepresentable_argument", &defaultUnrepresentableArgument, "A function with an unrepresentable default argument", py::arg("a") = MyClass{});
@@ -127,6 +153,7 @@ could be another, but it's not added yet.)");
         #endif
         ;
 
+    // TODO enable these for nanobind
     #if PYBIND11_VERSION_MAJOR*100 + PYBIND11_VERSION_MINOR >= 203
     pybind23
         .def_property("writeonly", nullptr, &MyClass23::setFoo, "A write-only property")
@@ -145,6 +172,8 @@ could be another, but it's not added yet.)");
         #endif
         ;
 
+    // TODO enable these for nanobind? or maybe drop some backwards compat
+    // TODO pos_only not in nanobind
     #if PYBIND11_VERSION_MAJOR*100 + PYBIND11_VERSION_MINOR >= 206
     pybind26
         .def_static("positional_only", &MyClass26::positionalOnly, "Positional-only arguments", py::arg("a"), py::pos_only{}, py::arg("b"))

documentation/test_python/test_nanobind.py

@@ -0,0 +1,47 @@
+#
+#   This file is part of m.css.
+#
+#   Copyright © 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024
+#             Vladimír Vondruš <[email protected]>
+#
+#   Permission is hereby granted, free of charge, to any person obtaining a
+#   copy of this software and associated documentation files (the "Software"),
+#   to deal in the Software without restriction, including without limitation
+#   the rights to use, copy, modify, merge, publish, distribute, sublicense,
+#   and/or sell copies of the Software, and to permit persons to whom the
+#   Software is furnished to do so, subject to the following conditions:
+#
+#   The above copyright notice and this permission notice shall be included
+#   in all copies or substantial portions of the Software.
+#
+#   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+#   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+#   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+#   DEALINGS IN THE SOFTWARE.
+#
+
+import copy
+import sys
+import unittest
+
+from python import State, parse_pybind_signature, default_config
+
+from . import BaseInspectTestCase
+
+class Signatures(BaseInspectTestCase):
+    def test(self):
+        sys.path.append(self.path)
+        import pybind_signatures
+        self.run_python({
+            # TODO false_positives ???
+            'INPUT_MODULES': [pybind_signatures],
+            'PYBIND11_COMPATIBILITY': True, # TODO don't rely on this
+            'NANOBIND_COMPATIBILITY': True
+        })
+        self.assertEqual(*self.actual_expected_contents('pybind_signatures.html', '../pybind_signatures/pybind_signatures.html'))
+        self.assertEqual(*self.actual_expected_contents('pybind_signatures.MyClass.html', '../pybind_signatures/pybind_signatures.MyClass.html'))
+        # TODO ??
+        # self.assertEqual(*self.actual_expected_contents('false_positives.html'))