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

Cannot generate Sphinx docs for lsst.afw.display.BLACK

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: To Do
    • Resolution: Unresolved
    • Fix Version/s: None
    • Component/s: afw
    • Labels:
      None

      Description

      As part of DM-16858, I tried to link to `lsst.afw.display.BLACK` but the link would not resolve. BLACK and its related constants also do not appear in the package documentation, despite being provided by __all__. Behavior does not change under the following changes:

      • Adding a one-line docstring to BLACK
      • Changing __all__ from a tuple to a list

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            Krzysztof Findeisen: short answer is that we need the include-all-objects flag to make this happen, as in:

            .. automodapi:: lsst.afw.display
               :no-main-docstr:
               :no-inheritance-diagram:
               :include-all-objects:

            automodapi doensn't have a way of making this a default, so I'll have to either upstream a change to automodapi, or update the templates to include this.

            I also can't get my own docstrigs to be used — I'm always getting an autogenerated Pybind11 docstring for these constants.

            Show
            jsick Jonathan Sick added a comment - Krzysztof Findeisen : short answer is that we need the include-all-objects flag to make this happen, as in: .. automodapi:: lsst.afw.display :no-main-docstr: :no-inheritance-diagram: :include-all-objects: automodapi doensn't have a way of making this a default, so I'll have to either upstream a change to automodapi, or update the templates to include this. I also can't get my own docstrigs to be used — I'm always getting an autogenerated Pybind11 docstring for these constants.
            Hide
            krzys Krzysztof Findeisen added a comment -

            Thanks for looking into this. I'm a bit baffled by the idea of lsst.afw.display.BLACK having a Pybind11 docstring, since it's defined in Python.

            Show
            krzys Krzysztof Findeisen added a comment - Thanks for looking into this. I'm a bit baffled by the idea of lsst.afw.display.BLACK having a Pybind11 docstring, since it's defined in Python .
            Hide
            krzys Krzysztof Findeisen added a comment -

            I don't think that's pybind11's fault; I think that's the docstring for str itself. See e.g. https://stackoverflow.com/questions/41236007/create-object-type-from-a-string.

            Show
            krzys Krzysztof Findeisen added a comment - I don't think that's pybind11's fault; I think that's the docstring for str itself. See e.g. https://stackoverflow.com/questions/41236007/create-object-type-from-a-string .
            Hide
            jsick Jonathan Sick added a comment -

            Ah my local build failed so my path must not be using the new afw.

            Show
            jsick Jonathan Sick added a comment - Ah my local build failed so my path must not be using the new afw.
            Hide
            tjenness Tim Jenness added a comment -
            Show
            tjenness Tim Jenness added a comment - I can confirm that https://pipelines.lsst.io/v/weekly/modules/lsst.afw.display/index.html does not include "BLACK.
            Hide
            jsick Jonathan Sick added a comment -

            I've moved this out of the backlog to check when we refresh the Pipelines documentation infrastructure and then more actively debug the afw.display documentation at that point.

            Show
            jsick Jonathan Sick added a comment - I've moved this out of the backlog to check when we refresh the Pipelines documentation infrastructure and then more actively debug the afw.display documentation at that point.

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              krzys Krzysztof Findeisen
              Watchers:
              Jonathan Sick, Krzysztof Findeisen, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:

                  Jenkins Builds

                  No builds found.