search

RobotLocomotion / drake

Model-based design and verification for robotics.
https://drake.mit.edu
Other
3.32k stars 1.26k forks source link

pydrake sphinx: Bad word wrapping with Doxygen -> Sphinx bulleted lists #14570

Closed EricCousineau-TRI closed 1 year ago

EricCousineau-TRI commented 3 years ago

As of nightly-release @ 2f41e7f8b: https://drake.mit.edu/pydrake/pydrake.systems.sensors.html#pydrake.systems.sensors.CameraInfo

image

https://drake.mit.edu/pydrake/pydrake.geometry.render.html#pydrake.geometry.render.ClippingRange

image

jamiesnape commented 3 years ago

This has always been the case, unfortunately. Sphinx expects one exception per line, and we never got around to unwrapping lines.

EricCousineau-TRI commented 3 years ago

Yup, didn't mean to imply this is a novel failure. May add weight to considering other solutions for web deployment, like Breathe.

mwoehlke-kitware commented 2 years ago

Can someone briefly explain how these are generated? (As in, hints to someone trying to fix this where to go looking?)

jwnimmer-tri commented 2 years ago

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.

jwnimmer-tri commented 1 year ago

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.