autodoc: automodule compatibility with nanobind

[keltonhalbert]

Describe the bug

I wasn't entirely sure if this should be under "bug" or "feature request", so please feel free to adjust the tag. I ultimately settled on "bug" because from the user-end, it's unexpected behavior.

The nanobind library for generating python bindings is a lighter-weight and more performant alternative offshoot of pybind11 from the same project author.

Currently, things like autofunction and autoclass work just fine with Sphinx. However, automodule fails to discover any functions (they have to be manually annotated). From the library author:

Some of the sphinx auto* tools don't recognize nanobind functions because they are based on a custom type nb_func instead of being a Python builtin or a C function.

I don't know if it further complicates things, but it also supports compiled submodules:

parent_module.submodule_1.function1
parent_module.submodule_2.function2

Functions and submodules are visible via dir(), and __all__ attributes can be created (though are not present by default). Currently, however, no functions are discoverable in modules or submodules unless manually annotated with autofunction.

Is supporting automodule discovery with nanobind something that would be considered for Sphinx? Are there any recommendations for how to get started with a PR for this, or perhaps where to focus efforts towards that?

How to Reproduce

This repository can be used for testing with sphinx, though does not have a conf.py set up: https://github.com/wjakob/nanobind_example

Environment Information

Please paste all output below into the bug report template



Platform:              linux; (Linux-4.18.0-553.56.1.el8_10.x86_64-x86_64-with-glibc2.28)
Python version:        3.13.3 | packaged by conda-forge | (main, Apr 14 2025, 20:44:03) [GCC 13.3.0])
Python implementation: CPython
Sphinx version:        8.3.0
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.1

Sphinx extensions

sphinx.ext.autodoc

Additional context

No response

[keltonhalbert]

I was able to mess around a little with the internals and get automodule to recognize nanobind functions, but it is not pretty:

class FunctionDocumenter(Documenter):
    """Specialized Documenter subclass for functions."""

    props: _FunctionDefProperties

    __docstring_signature__ = True

    objtype = 'function'
    member_order = 30

    @classmethod
    def can_document_member(
        cls: type[Documenter], member: Any, membername: str, isattr: bool, parent: Any
    ) -> bool:

        if '__nb_signature__' in list(dir(member)):
            sig = member.__nb_signature__[0][0]
            if sig.startswith("def"): return True
        # supports functions, builtins and bound methods exported at the module level
        return (
            inspect.isfunction(member)
            or inspect.isbuiltin(member)
            or (inspect.isroutine(member) and isinstance(parent, ModuleDocumenter))
        )

This fails for discovering classes, of course, and poses a whole different set of issues. The classes get filtered out before getting handed to ClassDocumenter by _member_finder.py:_filter_members due to inspect.getddoc failing Perhaps there are better ways to handle discovery? This was just the naive approach...

Is this something better suited for an extension, instead? I realize that handling edge cases for specific native bindings is not ideal...