Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-15461

“Hidden” class confuses Sphinx automod.

    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

            Hide
            swinbank John Swinbank added a comment -

            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?

            Show
            swinbank John Swinbank added a comment - 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?
            Hide
            price Paul Price added a comment -

            Nothing to add, sorry.

            Show
            price Paul Price added a comment - Nothing to add, sorry.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                swinbank John Swinbank
                Watchers:
                David Staker [X] (Inactive), John Swinbank, Jonathan Sick, Paul Price
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Summary Panel