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

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

    Details

    • Type: Bug
    • Status: In Progress
    • 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.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                krzys Krzysztof Findeisen
                Watchers:
                Jonathan Sick, Krzysztof Findeisen
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Summary Panel