Add constants to API reference

[larshinueber]

Hi all,

I was looking at how to document the constants module.
From what I found, I dont think it is possible to document a module attribute in the pybind11 exposure directly, since these are represented by variables in Python. When trying to document them in Sphinx using autodoc, the docstring will then just show the generic docstring of the variable type (e.g. float or complex), similar to what is returned by the help() function.

To avoid this, I would propose to overwrite these automatically-generated docstrings in Sphinx with just the type information and then add the docstrings in the .rst file. This breaks the philosophy of having the docstrings right next to the exposures, and creates a mismatch between the docstrings shown on the API reference and returned by the help() function (and in the future possible stubs/type-hints).

But since there is (seemingly) no way around this at the moment and the constants module doesn't change frequently, I would argue that this acceptable at the moment and outweighed by having a module documentation at all (?).

What do you think? See a draft version of the docs here:

[DominicDirkx]

I remember looking into this a while ago and also not finding any solution, so this is great!

One thing: could you remove the 'long' constants? They're no different than the regular ones in Python , and will just lead to confusion.

Thanks so much for setting this up!

[larshinueber]

Yes, going through the pybind- and Sphinx-specifics was indeed a journey 😅

Long constants should be removed now :)

[DominicDirkx]

And merged, great to have this finally 👏