C++ bindings and documentation.
DinoBektesevic opened this issue · 2 comments
Several issues are present here, none very high on the priority list.
One is that all our bindings are at the moment in 1 file. While pybind11 allows only 1 PYBIND11_MODULE macro it is, nonetheless, possible to split the bindings in multiple files as documented here. The motivation for doing something like that is to better handle the documentation of the C++ code which would make the current bindings.cpp grow very long indeed. Bonus side-effects could be faster compilation, parallel compilation, incremental builds, more readable pybind interface and better code organization for the C++ code.
Because Sphinx is a general documentation tool this documentation is provided in the style more common to C++. This is ok for now since almost no documentation exists for the C++ code, but given that these are Python bindings we should aim to provide a more Python friendly documentation. Example on how to do that was done for PSF class in #184.
Turning off the C++ style function signatures (valid for the lifespan of options object, in this case the whole module)
py::options options;
options.disable_function_signatures();produces a very pythonic documentation.
In terms of overall documentation, I would like to redo the C++ documentation from scratch. I had been thinking of the inherited, no-op classes. But I would be happy to discuss more.
Dino broke the bindings up during the Eigen PR and we have significantly increased the documentation coverage.