Details
-
Type:
Story
-
Status: To Do
-
Resolution: Unresolved
-
Fix Version/s: None
-
Component/s: None
-
Labels:None
-
Team:SQuaRE
Description
meas_base plugins are registered using makeSingleFramePlugin (or makeForcedPlugin). Those functions create “throwaway” classes SingleFrameFromGenericPlugin and ForcedFromGenericPlugin, of which the resulting plugins are then instances.
In other words, we end up with (e.g.) a measurement plugin called SingleFrameInputCountPlugin which has class lsst.meas.base.wrappers.GenericPlugin.makeSingleFramePlugin.<locals>.SingleFrameFromGenericPlugin. As the locals implies, there's no way to instantiated that class directly.
Unfortunately, this upsets Sphinx/automodapi. There seem to be two alternatives, both of which generate warnings. Simply using automodapi generates warnings of the form:
meas_base/doc/meas_base/index.rst:57: WARNING: Could not import class or module 'lsst.meas.base.wrappers.SingleFrameFromGenericPlugin' specified for inheritance diagram
|
An attempt to work around this by telling automodapi to skip these classes generates warnings like:
/meas_base/doc/meas_base/index.rst:41: WARNING: Tried to skip objects {'SingleFrameFromGenericPlugin', 'ForcedFromGenericPlugin'} in module lsst.meas.base, but they were not present. Ignoring.
|
Neither of these warnings are fatal, but neither are they very satisfying.
Attachments
Issue Links
Activity
Nothing to add, sorry.
Paul Price
added a comment - Nothing to add, sorry.
Naïvely, it seems like there are two ways one could address this issue.
One is to change automodapi's find_mod_objs function to be more discriminating about what it returns: it's easy enough to come up with heuristics that will cause it not to return the objects which confuse Sphinx. That said, I'm worried that heuristics which happen to work in this particular case may break in other, perfectly reasonable, situations — doing this properly would take some thought. Further, “hiding” objects like this means we'll never see docstrings corresponding to this code.
Alternatively, we could change the way that measurement plugins are instantiated in meas_base. It seems like the confusion stems from a rather elaborate way to share code between “single frame” and “forced” plugins, and I wonder if with a little thought and perhaps a few extra characters we might come up with a scheme which is perhaps a little more verbose but ultimately clearer both to the human reader and to automodapi. Since Paul Price seems to be the originator of those code, I wonder if he has any thoughts?