[BUG]: Docs for .doc() are incomplete

[ianhbell]

Problem description

The example in the docs for docstrings (https://nanobind.readthedocs.io/en/latest/basics.html#docstrings) only works if the __doc__ attribute of the extension is imported. Otherwise you get the nice generated info on the exported things, but the custom module text misses the custom text.

Reproducible example code

No response

[wjakob]

I don't think I understand the reported issue well enough from your description. If I import the extension, I do see the docstring via help().

[ianhbell]

I took the nanobind_example, added a doc field like so:

#include <nanobind/nanobind.h>

namespace nb = nanobind;

using namespace nb::literals;

NB_MODULE(nanobind_example_ext, m) {
    m.doc() = "Some documentation for the example library";
    m.def("add", [](int a, int b) { return a + b; }, "a"_a, "b"_a);
}

but when you do help(nanobind_example), the requested doc doesn't appear:

Help on package nanobind_example:

NAME
    nanobind_example

PACKAGE CONTENTS
    nanobind_example_ext

DATA
    add = <nanobind.nb_func object>
        add(a: int, b: int) -> int

FILE
    /Users/ihb/mambaforge/lib/python3.10/site-packages/nanobind_example/__init__.py

but it does if you import the __doc__ variable in __init__.py (the glob import of from .... import * does not import variables starting with _) the docs do appear properly.

[ianhbell]

This is a doc-related fix, the docs need to indicate that you need to import __doc__ because that gets inserted into the content generated in the help() call

[wjakob]

Ah, I get it now. You are setting __doc__ on the _ext module, not the main one. I guess that kind of makes sense, no? How is this a nanobind bug?

[ianhbell]

Because the docs suggest that this should work, but you need some magic to actually get the docs to appear. It doesn't automatically

[wjakob]

It works in the case where your main module and extension module are the same thing. The case where those are split into two things is more complex. Help on improving the docs is definitely appreciated.

[ianhbell]

Ok good I'll add a short note about that for future readers.

[ianhbell]

All the docs and examples have the extension module and main module as separate things (as I do as well). It took me a while to figure out what was going wrong here.

[wjakob]

Closing this ticket since it is not a nanobind issue, and there is a separate PR in the example project.