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

Full API documentation is not generated for tasks in pipe_tasks

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Invalid
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None
    • Story Points:
      1
    • Team:
      Alert Production

      Description

      There are a few (several?) tasks under pipe_tasks where the sphinx automodapi directive is not called, just lsst-task-api-summary.

      This results in an uninformatively short excerpt of the docstrings in the documentation and most of the information written in the code docstrings is actually skipped. Also, there is no link generated with the class name, not even to the "Python API summary" page.

      As of writing, this is the case with e.g. ScaleZeroPointTask or ProcessCcdTask. For me, it seems that there was once a generic documentation template file for pipe_tasks which was manually modified in a few cases only.

      Counterexamples are assembleCoadd and dcrAssembleCoadd that have their automodapi directive explicitly in the top level pipe_tasks index.rst.

      This issue may be connected to the (lack of) numpydoc migration of docstrings.

      • Make a decision where the automodapi directive should go.
      • Update the documentation of each task under pipe_tasks in a consistent way.

        Attachments

          Issue Links

            Activity

            gkovacs Gabor Kovacs [X] (Inactive) created issue -
            gkovacs Gabor Kovacs [X] (Inactive) made changes -
            Field Original Value New Value
            Description There are a few (several?) tasks under {{pipe_tasks}} where the sphinx {{automodapi}} directive is not called, just {{lsst-task-api-summary}}.

            This results in an uninformatively terse excerpt of the docstrings in the documentation and most of the information written in the code docstrings is actually skipped. Also, there is no link generated with the class name, not even to the "Python API summary" page.

            As of writing, this is the case with e.g. {{ScaleZeroPointTask}} or {{ProcessCcdTask}}. For me, it seems that there was once a generic documentation template file for pipe_tasks which was manually modified in a few cases only.

            Counterexamples are {{assembleCoadd}} and {{dcrAssembleCoadd}} that have their {{automodapi}} directive explicitly in the top level pipe_tasks {{index.rst}}.

            This issue may be connected to the (lack of) numpydoc migration of docstrings.
             * Make a decision where the {{automodapi}} directive should go.
             * Update the documentation of each task under {{pipe_tasks in }}a consistent way.
            There are a few (several?) tasks under {{pipe_tasks}} where the sphinx {{automodapi}} directive is not called, just {{lsst-task-api-summary}}.

            This results in an uninformatively terse excerpt of the docstrings in the documentation and most of the information written in the code docstrings is actually skipped. Also, there is no link generated with the class name, not even to the "Python API summary" page.

            As of writing, this is the case with e.g. {{ScaleZeroPointTask}} or {{ProcessCcdTask}}. For me, it seems that there was once a generic documentation template file for pipe_tasks which was manually modified in a few cases only.

            Counterexamples are {{assembleCoadd}} and {{dcrAssembleCoadd}} that have their {{automodapi}} directive explicitly in the top level pipe_tasks {{index.rst}}.

            This issue may be connected to the (lack of) numpydoc migration of docstrings.
             * Make a decision where the {{automodapi}} directive should go.
             * Update the documentation of each task under {{pipe_tasks}} in a consistent way.
            gkovacs Gabor Kovacs [X] (Inactive) made changes -
            Description There are a few (several?) tasks under {{pipe_tasks}} where the sphinx {{automodapi}} directive is not called, just {{lsst-task-api-summary}}.

            This results in an uninformatively terse excerpt of the docstrings in the documentation and most of the information written in the code docstrings is actually skipped. Also, there is no link generated with the class name, not even to the "Python API summary" page.

            As of writing, this is the case with e.g. {{ScaleZeroPointTask}} or {{ProcessCcdTask}}. For me, it seems that there was once a generic documentation template file for pipe_tasks which was manually modified in a few cases only.

            Counterexamples are {{assembleCoadd}} and {{dcrAssembleCoadd}} that have their {{automodapi}} directive explicitly in the top level pipe_tasks {{index.rst}}.

            This issue may be connected to the (lack of) numpydoc migration of docstrings.
             * Make a decision where the {{automodapi}} directive should go.
             * Update the documentation of each task under {{pipe_tasks}} in a consistent way.
            There are a few (several?) tasks under {{pipe_tasks}} where the sphinx {{automodapi}} directive is not called, just {{lsst-task-api-summary}}.

            This results in an uninformatively short excerpt of the docstrings in the documentation and most of the information written in the code docstrings is actually skipped. Also, there is no link generated with the class name, not even to the "Python API summary" page.

            As of writing, this is the case with e.g. {{ScaleZeroPointTask}} or {{ProcessCcdTask}}. For me, it seems that there was once a generic documentation template file for pipe_tasks which was manually modified in a few cases only.

            Counterexamples are {{assembleCoadd}} and {{dcrAssembleCoadd}} that have their {{automodapi}} directive explicitly in the top level pipe_tasks {{index.rst}}.

            This issue may be connected to the (lack of) numpydoc migration of docstrings.
             * Make a decision where the {{automodapi}} directive should go.
             * Update the documentation of each task under {{pipe_tasks}} in a consistent way.
            swinbank John Swinbank made changes -
            Link This issue duplicates DM-15554 [ DM-15554 ]
            swinbank John Swinbank made changes -
            Story Points 1
            Team Alert Production [ 10300 ]
            swinbank John Swinbank made changes -
            Resolution Done [ 10000 ]
            Status To Do [ 10001 ] Invalid [ 11005 ]

              People

              Assignee:
              Unassigned Unassigned
              Reporter:
              gkovacs Gabor Kovacs [X] (Inactive)
              Watchers:
              Gabor Kovacs [X] (Inactive), John Swinbank
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.