Repository navigation
Show inherited class methods by default in documentation? #4978
Description
In #4123, I split out Time's shape-changing methods to a new mixin class. It turned out that by doing that, these methods no longer automatically appear in the documentation. Rather, I had to add an :inherited-members: option to the time automodapi line: c9c4abf
For the same reason, the documentation for Quantity shows none of the methods inherited from ndarray and in the new solar_system_ephemeris science state class, I cannot link to its set method inherited from ScienceState.
Given this, I wondered whether we shouldn't simply include inherited members by default. Is there any strong reason not to?
Activity
eteq commentedon May 26, 2016
As I recall, we tried this a while back, and the biggest problem is that it ends up showing a lot of "junk" - e.g. lots of methods that are not particularly relevant for most use cases and therefore distracting to the user. For example, we do not want
Angleto show all theQuantityandndarraymethods because it's impossible to tell which are the new bitsAngleadds, and that's really what the API page forAngleis focused on. Similarly, lots of thendarraymethods are not particularly important for understanding how to useQuantity.So with that in mind, I think it's a feature, not a bug, that you have to explicitly do
:inherited-members:- that way you can opt-in when relevant, but only when there's a specific reason to do so.eteq commentedon May 26, 2016
(But maybe
:inherited-members:has become smarter about what it shows since then? Might be useful just to see a before-and-after of what the docs look like with it turned on or off...)mhvk commentedon May 26, 2016
Ah, I see the problem for
Angle... Though forQuantity, the case is less clear, since we override about half the methods ofndarray, which are shown, but not those that just happen to do exactly what we want anyway...Also, while for
Time, I could just turn inheritance on, I'm slightly stuck forCoordinates, since I would want to show thereshapeetc. methods forSkyCoord(wouldn't I?) or theScienceStatemethods insolar_system_ephemeris, but not theQuantitymethods inAngle.Maybe a solution is that at the end of each "methods summary/attribute summary", by default also a list of methods inherited from the base classes is listed, each clickable. I'll see whether this might be relatively easy to add...
eteq commentedon May 26, 2016
👍 to the "clickable" list at the end - might be really tough to implement that cleanly, but it would work great if possible...