Best practices for Sphinx?

[keltonhalbert]

Nanobind's docstring does not conform to the expected format for Sphinx (e.g. first line of doc is the function signature, not a function summary).

Does anyone have an example of how they use nanobind with sphinx, or recommendations on best practices?

Edit: The issue was actually with the way autosummary behaves, and not with nanobind's function signature convention. I was misguided there. Still having issues getting other aspects to play well, like automodule, but it is likely a "skill issue" on my part

[wjakob]

I am surprised to hear this. I use Sphinx with all my nanobind-based projects, and on my end it understands the format where the first N lines are overloads.

So: further evidence needed, and I am also curious what you think the expected format is.

[keltonhalbert]

I have managed to dig a little bit more, and it turns out, I was partially mistaken. So, my apologies on that front, @wjakob! The issue was specifically with trying to generate docs with the autosummary extension.

When manually annotating individual functions with autodoc, it correctly interprets the signature from the first line, and behaves as expected. Apparenly, when using autosummary to generate pages for each function, it does not respect the settings of autodoc and results in output where the function signature leaks into parts of the documentation it shouldn't. After further research, this may be remedied with custom template files. Again, apologies for my confusion there. I'm new to Sphinx.

However, the only reason I was using autosummary is because I wanted a convenient way to automatically document my functions without having to manually annotate each function. I tried the autodoc api for automodule, but for some reason, it doesn't discover the methods within a module (unless manually annotated). I'm trying to track down what's causing it to not be discoverable, but haven't got there yet.

Edit: I should mention, the automodule use case is with compiled submodules, which could be part of the difficulty.

[keltonhalbert]

@wjakob I would be curious to know if you have made use of automodule or autosummary in your projects! I took a look at drjit, but it looked like a lot of manual annotation, and seemed like you maybe also kept all of your docs in .rst and generated header docs from them? If you have examples that make use of the previously mentioned extensions, I'd love to check them out.

I've also thought about using the .pyi stubs and letting Sphinx look at those, since that was enabled in 8.2.0, but I think I have to have them in the source tree to get those to work. I can't seem to force it to use the .pyi stubs when importing the compiled module.

[wjakob]

Some of the she 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.

This should likely be raised with them at some point. What I usually do is to list each of the functions manually 🤷

[keltonhalbert]

Cheers, thank you for the insight! 🫡
I might take up raising that issue with them.