Status: To Do
Fix Version/s: None
Component/s: Stack Documentation and UX
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:
Note that a version argument is not specified. This is problematic because it generates reStructuredText in the docstring that looks like this:
However, the deprecated reStructuredText directive requires an argument, which is the version when an API is to be removed:
Without the version parameter, the Sphinx build gets warnings like this:
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.