Python bindings need documentation

[alexreinking]

The de-facto standard tool for documenting Python projects is Sphinx, which unfortunately expects to scan Python sources as its default workflow. However, Sphinx is very powerful and can generate documentation by loading a module and reading the __doc__ strings off of classes and methods. There is some prior art in generating these doc-strings from Doxygen and pasting them into pybind11 objects:

1. https://github.com/pybind/pybind11_mkdoc
2. https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Supposedly nanobind (#6662) has better support for this, but the limiting factor in my (limited) testing is the quality of pybind11_mkdoc. We might want/need to roll our own thing that looks through Doxygen's XML output, since it mkdoc doesn't seem to do a great job with groups.

Additionally, if we do start using Sphinx, we might start wanting to phase out Doxygen and our bespoke tutorials web framework in lieu of Breathe (a Doxygen scanner for Sphinx) and custom reStructuredText extensions. For instance, Sphinx can already execute Python code and insert the output into the docs.

[steven-johnson]

since it mkdoc doesn't seem to do a great job with groups

Do you say this based on testing, or based on documentation?

[alexreinking]

based on ~15 min of testing

[ogencoglu]

Any update on this?

[steven-johnson]

Unfortunately, no; @alexreinking has been away from the project for a couple of months (we're hoping he'll be able to return in some capacity soon), and I have had most of my time diverted to other matters in the last couple of months. It really is a thing we know needs attention, we're just understaffed for this task at the moment.

[alexreinking]

My filing deadline is tomorrow, I will need a week to rest, and then I can ramp back up

[ogencoglu]

Understandable. Thank you for the swift reply!