Closed EricCousineau-TRI closed 1 year ago
This has always been the case, unfortunately. Sphinx expects one exception per line, and we never got around to unwrapping lines.
Yup, didn't mean to imply this is a novel failure. May add weight to considering other solutions for web deployment, like Breathe.
Can someone briefly explain how these are generated? (As in, hints to someone trying to fix this where to go looking?)
First to set the stage, this ticket is not very important in the overall landscape of Drake. Per a chat with @BetsyMcPhail it only got pulled onto the project board as an onboarding ticket for @alesgenova. It's fine to have @alesgenova (or any other new onboarding Kitware contributor) work on it, but I'd prefer if we could have you (@mwoehlke-kitware) focus the more important tickets from the board.
To the question, though:
In the https://github.com/RobotLocomotion/drake/tree/master/tools/workspace/pybind11 folder, the files mkdoc.py
and mkdoc_comment.py
are most of what controls the python docstring formatting, when converting C++ comments into Napoleon syntax.
The https://drake.mit.edu/doxygen_cxx/group__python__bindings.html page also has a bit more detail about the documentation generation.
Closing this as not planned. The current documentation transmogrification system is fundamentally broken and the only salvation will be to re-implement it from scratch using actual specifications and proper parsing.
As of
nightly-release
@ 2f41e7f8b: https://drake.mit.edu/pydrake/pydrake.systems.sensors.html#pydrake.systems.sensors.CameraInfohttps://drake.mit.edu/pydrake/pydrake.geometry.render.html#pydrake.geometry.render.ClippingRange