Merge pull request #17597 from melissawm/legacy-directive

doc/source/_static/scipy.css

@@ -79,7 +79,7 @@ Nat Methods 8, 441 (2011). https://doi.org/10.1038/nmeth.1618
   margin-right: auto;
 }
 
-  .sd-card .sd-card-header {
+.sd-card .sd-card-header {
   border: none;
   background-color:white;
   color: #150458 !important;
@@ -170,3 +170,18 @@ html[data-theme=dark] .sd-card .sd-card-footer {
   padding: 0px 0px 0px 0px;
   text-align: left;
 }
+
+/* Legacy admonition */
+
+div.admonition-legacy {
+  border-color: var(--pst-color-warning);
+}
+
+.admonition-legacy.admonition > .admonition-title:before {
+  color: var(--pst-color-warning);
+  content: var(--pst-icon-admonition-attention);
+}
+
+.admonition-legacy.admonition > .admonition-title:after {
+  background-color: var(--pst-color-warning);
+}

doc/source/conf.py

@@ -5,6 +5,8 @@
 import sys
 import warnings
 from datetime import date
+from docutils import nodes
+from docutils.parsers.rst import Directive
 
 import matplotlib
 import matplotlib.pyplot as plt
@@ -416,3 +418,58 @@ def linkcode_resolve(domain, info):
 SphinxDocString._str_examples = _rng_html_rewrite(
     SphinxDocString._str_examples
 )
+
+
+class LegacyDirective(Directive):
+    """
+    Adapted from docutils/parsers/rst/directives/admonitions.py
+
+    Uses a default text if the directive does not have contents. If it does,
+    the default text is concatenated to the contents.
+
+    """
+    has_content = True
+    node_class = nodes.admonition
+    optional_arguments = 1
+
+    def run(self):
+        try:
+            obj = self.arguments[0]
+        except IndexError:
+            # Argument is empty; use default text
+            obj = "submodule"
+        text = (f"This {obj} is considered legacy and will no longer receive "
+                "updates. This could also mean it will be removed in future "
+                "SciPy versions.")
+
+        try:
+            self.content[0] = text+" "+self.content[0]
+        except IndexError:
+            # Content is empty; use the default text
+            source, lineno = self.state_machine.get_source_and_line(
+                self.lineno
+            )
+            self.content.append(
+                text,
+                source=source,
+                offset=lineno
+            )
+        text = '\n'.join(self.content)
+        # Create the admonition node, to be populated by `nested_parse`
+        admonition_node = self.node_class(rawsource=text)
+        # Set custom title
+        title_text = "Legacy"
+        textnodes, _ = self.state.inline_text(title_text, self.lineno)
+        title = nodes.title(title_text, '', *textnodes)
+        # Set up admonition node
+        admonition_node += title
+        # Select custom class for CSS styling
+        admonition_node['classes'] = ['admonition-legacy']
+        # Parse the directive contents
+        self.state.nested_parse(self.content, self.content_offset,
+                                admonition_node)
+        return [admonition_node]
+
+
+def setup(app):
+    app.add_directive("legacy", LegacyDirective)

doc/source/dev/contributor/rendering_documentation.rst

@@ -287,6 +287,43 @@ reproduce the results of the example exactly, so examples using random data
 should not refer to precise numerical values based on random data or rely on
 them to make their point.
 
+Legacy directive
+~~~~~~~~~~~~~~~~
+
+If a function, module or API is in *legacy* mode, meaning that it is kept around
+for backwards compatibility reasons, but is not recommended to use in new code,
+you can use the ``.. legacy::`` directive.
+
+By default, if used with no arguments, the legacy directive will generate the
+following output:
+
+.. legacy::
+
+
+We strongly recommend that you also add a custom message, such as a new API to
+replace the old one. This message will be appended to the default message::
+
+   .. legacy::
+
+      New code should use :mod:`scipy.fft`.
+
+will create the following output:
+
+.. legacy::
+
+   New code should use :mod:`scipy.fft`.
+
+Finally, if you want to mention a function, method (or any custom object)
+instead of a *submodule*, you can use an optional argument::
+
+    .. legacy:: function
+
+This will create the following output:
+
+.. legacy:: function
+
+---
+
 .. _GitHub: https://github.com/
 .. _CircleCI: https://circleci.com/vcs-authorize/
 .. _Sphinx: https://www.sphinx-doc.org/en/master/

scipy/fftpack/__init__.py

@@ -3,10 +3,9 @@
 Legacy discrete Fourier transforms (:mod:`scipy.fftpack`)
 =========================================================
 
-.. warning::
+.. legacy::
 
-   This submodule is now considered legacy, new code should use
-   :mod:`scipy.fft`.
+   New code should use :mod:`scipy.fft`.
 
 Fast Fourier Transforms (FFTs)
 ==============================

scipy/interpolate/_interpolate.py

@@ -385,6 +385,8 @@ class interp1d(_Interpolator1D):
     """
     Interpolate a 1-D function.
 
+    .. legacy:: class
+
     `x` and `y` are arrays of values used to approximate some function f:
     ``y = f(x)``. This class returns a function whose call method uses
     interpolation to find the value of new points.

tools/refguide_check.py

@@ -52,7 +52,6 @@
 directives.register_directive('seealso', SeeAlso)
 directives.register_directive('only', Only)
 
-
 BASE_MODULE = "scipy"
 
 PUBLIC_SUBMODULES = [
@@ -341,7 +340,7 @@ def validate_rst_syntax(text, name, dots=True):
         return False, "ERROR: %s: no documentation" % (name,)
 
     ok_unknown_items = set([
-        'mod', 'currentmodule', 'autosummary', 'data',
+        'mod', 'currentmodule', 'autosummary', 'data', 'legacy',
         'obj', 'versionadded', 'versionchanged', 'module', 'class', 'meth',
         'ref', 'func', 'toctree', 'moduleauthor', 'deprecated',
         'sectionauthor', 'codeauthor', 'eq', 'doi', 'DOI', 'arXiv', 'arxiv'