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

Deprecation process is generating Sphinx syntax warnings

    Details

    • Templates:
    • Team:
      Architecture

      Description

      The new guidelines on Deprecating interfaces direct developers to use the @deprecated decorator such that the version when an API is removed is not specified. A real life example is from lsst.afw.table.exposure.ExposureRecord:

      @continueClass  # noqa: F811
      class ExposureRecord:
          @deprecated(reason="Replaced with getPhotoCalib (will be removed after v18)", category=FutureWarning)
          def getCalib(self, *args, **kwargs):
              return self._getCalib(*args, **kwargs)
       
          @deprecated(reason="Replaced with setPhotoCalib (will be removed after v18)", category=FutureWarning)
          def setCalib(self, *args, **kwargs):
              self._setCalib(*args, **kwargs)
      

      Note that a version argument is not specified. This is problematic because it generates reStructuredText in the docstring that looks like this:

      .. deprecated::
       
         Replaced with setPhotoCalib (will be removed after v18)
      

      However, the deprecated reStructuredText directive requires an argument, which is the version when an API is to be removed:

      .. deprecated:: 3.1
         Use :func:`spam` instead.
      

      Without the version parameter, the Sphinx build gets warnings like this:

      afw/python/lsst/afw/table/exposure/exposureContinued.py:docstring of lsst.afw.table.ExposureRecord.getCalib:2: WARNING: Error in "deprecated" directive:
      1 argument(s) required, 0 supplied.
       
      .. deprecated::
      
      

      Additionally, because of the broken syntax, the deprecation warning isn't highlighted in the rendered API Reference.

      Either we need to modify the Deprecating interfaces to require a version parameter be specified as the version where an API will be deprecated (for example, v19 is likely for the ExposureRecord APIs, or we need to create a new ticket on SQuaRE to create a new Sphinx extension to monkey patch the deprecated directive to resolve these warnings and rendering issues.

        Attachments

          Activity

            People

            • Assignee:
              ktl Kian-Tat Lim
              Reporter:
              jsick Jonathan Sick
              Watchers:
              Jonathan Sick, Kian-Tat Lim
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:

                Summary Panel