From 6cfbd274737675440627880043863666cf2021af Mon Sep 17 00:00:00 2001
From: Pedro Algarvio <palgarvio@vmware.com>
Date: Thu, 16 Nov 2023 11:25:04 +0000
Subject: [PATCH] Show warning on modules which are getting deprecated into
 extensions

Signed-off-by: Pedro Algarvio <palgarvio@vmware.com>
---
 doc/conf.py | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/doc/conf.py b/doc/conf.py
index e5be1a13697..f1d28b14c47 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -3,12 +3,18 @@
 Sphinx documentation for Salt
 """
 import os
+import pathlib
 import re
+import shutil
 import sys
+import textwrap
 import time
 import types
 
 from sphinx.directives.other import TocTree
+from sphinx.util import logging
+
+log = logging.getLogger(__name__)
 
 # -- Add paths to PYTHONPATH ---------------------------------------------------
 try:
@@ -414,6 +420,36 @@ class ReleasesTree(TocTree):
         return rst
 
 
+def extract_module_deprecations(app, what, name, obj, options, lines):
+    """
+    Add a warning to the modules being deprecated into extensions.
+    """
+    # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-process-docstring
+    if what != "module":
+        # We're only interested in module deprecations
+        return
+
+    try:
+        deprecated_info = obj.__deprecated__
+    except AttributeError:
+        # The module is not deprecated
+        return
+
+    _version, _extension, _url = deprecated_info
+    msg = textwrap.dedent(
+        f"""
+        .. warning::
+
+            This module will be removed from Salt in version {_version} in favor of
+            the `{_extension} Salt Extension <{_url}>`_.
+
+        """
+    )
+    # Modify the docstring lines in-place
+    lines[:] = msg.splitlines() + lines
+
+
 def setup(app):
     app.add_directive("releasestree", ReleasesTree)
     app.connect("autodoc-skip-member", skip_mod_init_member)
+    app.connect("autodoc-process-docstring", extract_module_deprecations)