search

RobotLocomotion / drake

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

pydrake doc: Allow subclass opt-in to re-document superclass methods #15242

Open RussTedrake opened 3 years ago

RussTedrake commented 3 years ago

For example: https://github.com/RobotLocomotion/drake/blob/d22581cc1ccd86c4f8a7b23a9d33e02f760eb20c/solvers/dreal_solver.h#L94

Results in Solve appearing in doxygen: https://drake.mit.edu/doxygen_cxx/classdrake_1_1solvers_1_1_dreal_solver.html

but not in pydrake docs: https://drake.mit.edu/pydrake/pydrake.solvers.dreal.html?highlight=dreal#module-pydrake.solvers.dreal

jwnimmer-tri commented 3 years ago

Per https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html:

... For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the inherited-members option, in addition to members ...

For Doxygen, the using syntax is how we control what inherited functions we slurp into the subclass's API reference. It's valid to ask for a mechanism in Python to do the same, but I don't think it needs to be by scraping the C++ using statements. A python-specific syntax that we annotate onto the bindings files somewhere seems like a valid path to a solution as well.