How do I make sphinx understand the documentation information in static methods?

[riclarsson]

Hi any and all,

We decided to switch from pybind11 to nanobind.

This is a growth pain question.

I have a problem getting my sphinx documentation for static data and static methods working in nanobind. In pybind11, static methods produces nice documentation.

You can see this comparing our stable new and stable documentation. This page gives the method get_options, where nanobind seems to think it returns an instance of some of itself, and pybind11 shows the documentation.

Note that if I go into ipython and simply ? on /pyarts.arts.options.SpeciesTagType.get_options: pyarts.arts.options.SpeciesTagType.get_options?, I get the correct documentation. It just doesn't seem to propagate to sphinx.

I am wondering if there are workarounds here so that sphinx can see the documentation?

[wjakob]

How do you list the classes and their members? Have you tried registering them explicitly, like so?

.. autoclass:: class

   .. automethod:: method

It's possible that Sphinx thinks that the static methods are data, not functions.

[wjakob]

If that doesn't do it, then I fear that this is something that only the Sphinx team can fix.

[riclarsson]

Thank you for the advice. The core problem is definitely how sphinx interprets what nanobind types are what type.

The jinja template we are using for generating the class data, which is just a standard template with nothing special in it, does not work with nanobind.

The main reason is that nanobind produces types that are not seen as methods, but as attributes. The link above, the nanobind types never sees the methods tab. As a consequence, sphinx believes it should be using the :autoattribute: command rather than the :automethod: command...

[wjakob]

Have you opening an issue with the Sphinx team? It should be easy to distinguish callable from non-callable objects and use this to display static methods correctly.

[riclarsson]

No, I did not report it.

I am not sure how to report this in a manner that is clear for them to reproduce. Nor if it is just our implementation of the template that is wrong.

I can identify the problem but my only solution has been to completely ignore the automatic code and to sweep through the generated library to manually call the right command depending on the types.

[ianhbell]

I have the same issue. I noticed that when I added a listener in sphinx in my conf.py, like so:

def autodoc_process_handler(app, what, name, obj, options, lines, huh):
    print(what, name, obj, lines, obj.__doc__)
    
def setup(app):
    app.connect('autodoc-process-signature', autodoc_process_handler)

sphinx gives me output like this:

class teqpflsh._teqpflsh_impl.ChebyshevApproximation1D <class 'teqpflsh._teqpflsh_impl.ChebyshevApproximation1D'> (*args, **kwargs) None
attribute teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.count_x_for_y_many <nanobind.nb_method object at 0x104a23560>  count_x_for_y_many(self, arg0: ndarray[dtype=float64, shape=(*), order='C', device='cpu'], arg1: int, arg2: int, arg3: float, arg4: ndarray[dtype=float64, shape=(*), order='C', device='cpu'], /) -> None
attribute teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.eval <nanobind.nb_method object at 0x104a23120>  eval(self, arg: float, /) -> float
attribute teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.eval_many <nanobind.nb_method object at 0x104a23450>  eval_many(self, arg0: ndarray[dtype=float64, shape=(*), order='C', device='cpu'], arg1: ndarray[dtype=float64, shape=(*), order='C', device='cpu'], /) -> None
property teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.expansions <property object at 0x104a02c00>  (self) -> list[teqpflsh._teqpflsh_impl.ChebyshevExpansion]
attribute teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.get_intervals_containing_y <nanobind.nb_method object at 0x104a239a0>  get_intervals_containing_y(self, arg: float, /) -> list[teqpflsh._teqpflsh_impl.IntervalMatch]
attribute teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.get_x_for_y <nanobind.nb_method object at 0x104a23010>  get_x_for_y(self, *, y: float, bits: int = 64, max_iter: int = 100, boundsftol: float = 1e-13) -> list[tuple[float, int]]
property teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.monotonic_intervals <property object at 0x104a02ca0>  (self) -> list[teqpflsh::superancillary::IntervalMatch]
property teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.x_at_extrema <property object at 0x104a02c50>  (self) -> list[float]
property teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.xmax <property object at 0x104a02bb0>  (self) -> float
property teqpflsh._teqpflsh_impl.ChebyshevApproximation1D.xmin <property object at 0x104a02b10>  (self) -> float

but it is inferring incorrectly that the methods are attributes and thus gives no documentation.

[njroussel]

FWIW we worked around this by monkey patching sphinx:
https://github.com/mitsuba-renderer/mitsuba3/blob/master/docs/docs_api/conf.py#L810-L823
This is extremely brittle, as there seems to have been quite a few changes in that part of sphinx's source code in recent versions.

Another solution is to explicitly list the class members yourself, to bypass the "identification" process entirely - instead of relying on the autodoc to find and identify the members.

It's unclear to me if Sphinx already provides a way to alter the "identification" process of objects. I think that would be the correct fix to this issue.

[scottamain]

Thank you so much @njroussel, this patch works great for me! 🙏

Also pasting your conf.py code here for posterity (works with Sphinx 7.4.7):

def setup(app):
    import inspect
    from sphinx.util import inspect as sphinx_inspect

    # Sphinx inspects all objects in the module and tries to resolve their type
    # (attribute, function, class, module, etc.) by using its own functions in
    # `sphinx.util.inspect`. These functions misidentify certain nanobind
    # objects. We monkey patch those functions here.
    def mpatch_ismethod(object):
        if hasattr(object, '__name__') and type(object).__name__ == "nb_method":
            return True
        return inspect.ismethod(object)

    sphinx_inspect_isclassmethod = sphinx_inspect.isclassmethod
    def mpatch_isclassmethod(object, cls=None, name=None):
        if hasattr(object, '__name__') and type(object).__name__ == "nb_method":
            return False
        return sphinx_inspect_isclassmethod(object, cls,name)

    sphinx_inspect.ismethod = mpatch_ismethod
    sphinx_inspect.isclassmethod = mpatch_isclassmethod

[ianhbell]

My solution is also brittle, I wrote a script to parse, since my object hierarchy is flat enough:

import inspect 

class AutodocCollector:
    entries = []
    def __init__(self, module, dunder=False):
        for key in dir(module):
            thing = getattr(module, key)
            if key.startswith('__') and not dunder:
                continue
            
            if 'nanobind.nb_func' in str(type(thing)):
                self.parse_func(thing)
            elif 'enum.EnumType' in str(type(thing)):
                self.parse_enum(thing)
            elif 'nanobind.nb_type_0' in str(type(thing)):
                self.parse_class(thing)
            else:
                print(key, type(thing), thing.__name__, inspect.getmembers(thing))
            
    def add_entry(self, e):
        self.entries.append(e)
        
    def to_file(self, path, title):
        with open(path, 'w') as fp:
            fp.write(title+'\n')
            fp.write('='*len(title)+'\n\n')
            fp.write('\n\n'.join(self.entries))
                            
    def parse_func(self, thing):
        mother = inspect.getmodule(thing)
        self.add_entry(f'.. autofunction:: {mother.__name__}.{thing.__name__}\n\n    :teqpflsh:`{thing.__name__}`')
        
    def parse_enum(self, thing):
        mother = inspect.getmodule(thing)
        self.add_entry(f'.. autoclass:: {mother.__name__}.{thing.__name__}\n    :undoc-members:\n    :members:\n    :show-inheritance:\n\n    :teqpflsh:`{thing.__name__}`')
        
    def parse_class(self, thing):
        mother = inspect.getmodule(thing)
        members = inspect.getmembers(thing)
        e = f'.. autoclass:: {mother.__name__}.{thing.__name__}\n    :show-inheritance:'
        e += f'\n\n    C++ docs: :teqpflsh:`{thing.__name__}`'
        for name, member in members:
            if name.startswith('__'): continue
            if isinstance(member, property):
                e += '\n\n' + ' '*4 + f'.. autoproperty:: {name}\n'
            else:
                e += '\n\n' + ' '*4 + f'.. automethod:: {name}\n'
        self.add_entry(e)
            
if __name__ == '__main__':
    import teqpflsh
    ac = AutodocCollector(teqpflsh._teqpflsh_impl)
    ac.to_file('api/teqpflsh.rst', title='teqpflsh Package')

[VincentRouvreau]

If I understand well what happens in sphinx code, this is somewhere here:
https://github.com/sphinx-doc/sphinx/blob/aeeaeafc8a1198dc1b982d28bd23495a987aeb5d/sphinx/util/inspect.py#L357-L379

And especially when return type(unwrapped).__name__ != 'instancemethod' is tested.
Here, with Nanobind, the name is nb_method, contrary to PyBind11 where it is instancemethod.

@wjakob What was the reason to name it differently ?
I am ok that Sphinx could also add this test to be conform with Nanobind.

I opened sphinx-doc/sphinx#13823 on sphinx side.

UPDATE: Sorry for the noise, my issue was different and not for static method

[Yikai-Liao]

Hi, I am the developer of symusic, a library using nanobind, and I am trying to make the API Reference work. I found that previous solutions are not enough for my project, and I would like to paste my solution here.

It might not work for old or new version of sphinx, and I test it under 7.4.7

Demo here: https://symusic.readthedocs.io/en/latest/api/core/scores.html#symusic.core.ScoreTick.from_abc

Nanobind autodoc patch cheat sheet

Method detection

• sphinx.util.inspect.isfunction, isroutine, and ismethoddescriptor are monkey patched to return True for nanobind.nb_func / nanobind.nb_method.
• Reason: nanobind callables do not inherit Python's pure function descriptors, so the default autodoc discovery treated them as attributes and skipped signature extraction.
• The helper isnanobind(obj) (module check + type name check) centralizes the detection.

def isfunction(obj: Any) -> bool:
    return _orig_isfunction(obj) or isnanobind(obj)

def isroutine(obj: Any) -> bool:
    return _orig_isroutine(obj) or isnanobind(obj)

def ismethoddescriptor(obj: Any) -> bool:
    return _orig_ismethoddescriptor(obj) or isnanobind(obj)

Property type hints

• Nanobind property getters expose docstrings like value(self, /) -> symusic.core.TrackTickList but do not carry __annotations__.
• _nanobind_property_return_from_doc() parses the first line of the docstring and extracts the post--> portion.
• _patch_property_documenter() appends the parsed type as :type: in the directive header unless autodoc_typehints == "none".

def add_directive_header(self, sig: str) -> None:
    orig_add_directive_header(self, sig)
    if self.config.autodoc_typehints == "none":
        return

    func = self._get_property_getter()
    fallback = _nanobind_property_return_from_doc(func) if func else None
    if fallback:
        self.add_line('   :type: ' + fallback, self.get_sourcename())

Static factories and groupwise ordering

• _patch_method_documenter() inspects parent.__dict__[name]; if the descriptor is a nanobind.nb_func, mark it as static and emit :staticmethod:.
• The same hook lowers member_order by one so static factories lead their group.
• _patch_member_sorting() hooks Documenter.sort_members() to ensure any nanobind static factory gets its member_order adjusted before Sphinx performs the groupwise sort. It relies on _resolve_class_member() to recover the raw descriptor via the fully qualified name (e.g., symusic.core::ScoreTick.from_file).

def import_object(self, raiseerror: bool = False) -> bool:
    ret = orig_import_object(self, raiseerror)
    if not ret:
        return ret

    obj = self.parent.__dict__.get(self.object_name)
    if isinstance(obj, type(self.object)) and type(obj).__name__ == "nb_func" and isnanobind(obj):
        self._is_nanobind_static = True
        self.member_order -= 1
    return ret

def add_directive_header(self, sig: str) -> None:
    orig_add_directive_header(self, sig)
    if getattr(self, "_is_nanobind_static", False):
        self.add_line('   :staticmethod:', self.get_sourcename())

def sort_members(self, documenters, order):
    if order == "groupwise" and isinstance(self, ClassDocumenter):
        for documenter, _ in documenters:
            if isinstance(documenter, MethodDocumenter):
                resolved = _resolve_class_member(documenter)
                if resolved:
                    owner, _, raw = resolved
                    if type(raw).__name__ == "nb_func" and isnanobind(raw):
                        documenter.member_order = MethodDocumenter.member_order - 1
    return orig_sort_members(self, documenters, order)

Full patch reference

from __future__ import annotations

import importlib
from inspect import Parameter
from typing import Any, Optional

import sphinx.util.inspect as sphinx_inspect
from sphinx.ext.autodoc import (
    ClassDocumenter,
    Documenter,
    MethodDocumenter,
    PropertyDocumenter,
)
from sphinx.locale import __
from sphinx.util import logging
from sphinx.util.typing import stringify_annotation

logger = logging.getLogger(__name__)


def isnanobind(obj) -> bool:
    return (
        hasattr(type(obj), "__module__")
        and type(obj).__module__ == "nanobind"
        and type(obj).__name__ in ("nb_func", "nb_method")
    )


_orig_isfunction = sphinx_inspect.isfunction
def isfunction(obj: Any) -> bool:
    return _orig_isfunction(obj) or isnanobind(obj)
sphinx_inspect.isfunction = isfunction

_orig_isroutine = sphinx_inspect.isroutine
def isroutine(obj: Any) -> bool:
    return _orig_isroutine(obj) or isnanobind(obj)
sphinx_inspect.isroutine = isroutine

_orig_ismethoddescriptor = getattr(sphinx_inspect, "ismethoddescriptor", None)
if _orig_ismethoddescriptor:
    def ismethoddescriptor(obj: Any) -> bool:
        return _orig_ismethoddescriptor(obj) or isnanobind(obj)
    sphinx_inspect.ismethoddescriptor = ismethoddescriptor


def _nanobind_property_return_from_doc(func: Any) -> Optional[str]:
    if not isnanobind(func):
        return None

    doc = (getattr(func, "__doc__", "") or "").strip()
    if not doc:
        return None

    first_line = doc.splitlines()[0]
    if "->" not in first_line:
        return None

    return first_line.split("->", 1)[1].strip()


def _patch_property_documenter() -> None:
    orig_add_directive_header = PropertyDocumenter.add_directive_header

    def add_directive_header(self, sig: str) -> None:  # type: ignore[override]
        orig_add_directive_header(self, sig)

        if self.config.autodoc_typehints == "none":
            return

        func = self._get_property_getter()
        fallback_type = _nanobind_property_return_from_doc(func) if func else None
        if fallback_type:
            self.add_line('   :type: ' + fallback_type, self.get_sourcename())

    PropertyDocumenter.add_directive_header = add_directive_header


def _patch_method_documenter() -> None:
    orig_import_object = MethodDocumenter.import_object
    orig_add_directive_header = MethodDocumenter.add_directive_header

    def import_object(self, raiseerror: bool = False) -> bool:  # type: ignore[override]
        ret = orig_import_object(self, raiseerror)
        self._is_nanobind_static = False  # type: ignore[attr-defined]
        if not ret:
            return ret

        obj = self.parent.__dict__.get(self.object_name)
        if (
            isinstance(obj, type(self.object))
            and type(obj).__name__ == "nb_func"
            and isnanobind(obj)
        ):
            self._is_nanobind_static = True  # type: ignore[attr-defined]
            self.member_order -= 1
        return ret

    def add_directive_header(self, sig: str) -> None:  # type: ignore[override]
        orig_add_directive_header(self, sig)

        if getattr(self, "_is_nanobind_static", False):  # type: ignore[attr-defined]
            self.add_line('   :staticmethod:', self.get_sourcename())

    MethodDocumenter.import_object = import_object
    MethodDocumenter.add_directive_header = add_directive_header


def _resolve_class_member(documenter: MethodDocumenter) -> tuple[object, str, Any] | None:
    if "::" not in documenter.name:
        return None

    modname, qualname = documenter.name.split("::", 1)
    if not qualname:
        return None

    chunks = qualname.split(".")
    if len(chunks) < 2:
        return None

    try:
        module = importlib.import_module(modname)
    except Exception:  # pragma: no cover
        return None

    owner: Any = module
    for chunk in chunks[:-1]:
        owner = getattr(owner, chunk, None)
        if owner is None:
            return None

    member_name = chunks[-1]
    owner_dict = getattr(owner, "__dict__", {})
    raw = owner_dict.get(member_name)
    if raw is None:
        raw = getattr(owner, member_name, None)

    if raw is None:
        return None

    return owner, member_name, raw


def _patch_member_sorting() -> None:
    orig_sort_members = Documenter.sort_members

    def sort_members(self, documenters, order):  # type: ignore[override]
        if order == "groupwise" and isinstance(self, ClassDocumenter):
            for documenter, _ in documenters:
                if isinstance(documenter, MethodDocumenter):
                    resolved = _resolve_class_member(documenter)
                    if not resolved:
                        continue

                    _, _, raw = resolved
                    if type(raw).__name__ == "nb_func" and isnanobind(raw):
                        documenter.member_order = MethodDocumenter.member_order - 1

        return orig_sort_members(self, documenters, order)

    Documenter.sort_members = sort_members


_patch_property_documenter()
_patch_method_documenter()
_patch_member_sorting()

[wjakob]

Thank you for the thorough summary! It would be nice if Sphinx would just work out of the box, as hot-patching is inherently fragile. Previously, they were open to making nanobind-specific modifications (e.g., https://github.com/sphinx-doc/sphinx/pull/13836/files).

What else do you think is needed? Would you be willing to make a Sphinx PR with those modifications you had to insert?

[Yikai-Liao]

Thank you for the thorough summary! It would be nice if Sphinx would just work out of the box, as hot-patching is inherently fragile. Previously, they were open to making nanobind-specific modifications (e.g., https://github.com/sphinx-doc/sphinx/pull/13836/files).

What else do you think is needed? Would you be willing to make a Sphinx PR with those modifications you had to insert?

I would like to, but I find my patch does not work well on Sphinx 8.

[Yikai-Liao]

And it would help a lot if nanobind could expose standard introspection hooks on its descriptors.

If nb_func/nb_method populated __text_signature__ (PEP 362) and/or real __annotations__ (PEP 3107) for both methods and property getters/setters, then vanilla inspect.signature() would “just work” without downstream monkey patches.

For example, in my patch, I have to extract the property value in the first line of __doc__, like getter(self, /) -> ReturnType, and this is not a standard way to extract the return type.

Would adding those metadata fields on the nanobind side be feasible?

[Yikai-Liao]

Well, add __text_signature__ and __annotations__ is not hard.

I try to add using codex 5.1 and it works. I have created a PR #1221