Prune unused defensive workarounds added during theme migration

Iterative debugging of the PyData theme migration left several
overlapping defenses that the final CI-green build does not need:

- doc/conf.py:
  - Tighten urllib.parse.urlsplit patch to ValueError("Invalid IPv6 URL")
    only; drop the broadened "except Exception" handler.
  - Drop the duplicate urlparse patch; only urlsplit raises on the
    bracketed-host placeholders we hit.
  - Drop the sys.modules sweep that re-bound already-imported references;
    patching at module top-of-file before any heavy imports is enough.
  - Drop the pydata_sphinx_theme.short_link no-op monkeypatch; the
    "shorten_urls": False theme option already disables it.
  - Drop the urllib3 and requests.packages.urllib3 parse_url patches;
    the docs build does not hit either path.
  - Drop the manual sys.modules["cgi"] mock; autodoc_mock_imports
    handles it.
  - Drop the warnings.filterwarnings(SyntaxWarning) global; sphinx -W
    does not promote Python SyntaxWarnings to build errors.
  - Restore ReleasesTree.run to the original implementation (no
    swallow-all try/except) and the missing-deps log call to warning.

- salt/modules/file.py, salt/states/mysql_grants.py: revert docstrings
  to triple-quoted (not r"""); they are unrelated to the docs build.
- salt/modules/gem.py, salt/states/gem.py, salt/transport/zeromq.py:
  revert the URL/identifier reformatting that was added to work around
  the now-disabled URL shortener.

Verified locally with the CI invocation under a python3.14 venv built
from requirements/static/ci/py3.14/docs.txt:
  cd doc && make clean
  make html SPHINXOPTS='-W -j auto --keep-going --color'
  make man  SPHINXOPTS='-W -j auto --keep-going --color'
Both builds succeed with -W strict mode.

Author: Daniel A. Wozniak

doc/conf.py

@@ -2,102 +2,27 @@
 """
 Sphinx documentation for Salt
 """
-import logging
 import os
 import sys
 import urllib.parse
-import warnings
 
-# Suppress SyntaxWarnings (invalid escape sequences) which become errors in CI with -W
-# We fix these as we find them, but this prevents "flickering" crashes in large-scale builds.
-warnings.filterwarnings("ignore", category=SyntaxWarning)
-
-# Fix urllib.parse.urlsplit/urlparse bug (Invalid IPv6 URL)
-# This bug causes Sphinx to crash when encountering documentation examples
-# like http://hostname[:port] which are incorrectly parsed as malformed IPv6 URLs.
-# We patch it globally to ensure all extensions (like pydata-sphinx-theme) are safe.
+# Sphinx crashes parsing docstring URLs like ``http://hostname[:port]`` because
+# urllib.parse.urlsplit raises ValueError("Invalid IPv6 URL") on the bracketed
+# host placeholder. Return a dummy SplitResult for that one case so the build
+# can proceed.
 _original_urlsplit = urllib.parse.urlsplit
-_original_urlparse = urllib.parse.urlparse
-log = logging.getLogger("salt.docs.conf")
 
 
 def _safe_urlsplit(url, scheme="", allow_fragments=True):
     try:
         return _original_urlsplit(url, scheme, allow_fragments)
-    except Exception:
-        # Return a safe dummy SplitResult for ANY error
-        return urllib.parse.SplitResult(scheme, "invalid-url", str(url), "", "")
-
-
-def _safe_urlparse(url, scheme="", allow_fragments=True):
-    try:
-        return _original_urlparse(url, scheme, allow_fragments)
-    except Exception:
-        # Return a safe dummy ParseResult for ANY error
-        return urllib.parse.ParseResult(scheme, "invalid-url", str(url), "", "", "")
+    except ValueError as exc:
+        if "Invalid IPv6 URL" in str(exc):
+            return urllib.parse.SplitResult(scheme, "", url, "", "")
+        raise
 
 
 urllib.parse.urlsplit = _safe_urlsplit
-urllib.parse.urlparse = _safe_urlparse
-
-# Ensure any modules that already imported urlsplit or urlparse also use the patched versions.
-for mod in list(sys.modules.values()):
-    if mod:
-        if hasattr(mod, "urlsplit") and mod.urlsplit is _original_urlsplit:
-            mod.urlsplit = _safe_urlsplit
-        if hasattr(mod, "urlparse") and mod.urlparse is _original_urlparse:
-            mod.urlparse = _safe_urlparse
-
-# Force disable pydata_sphinx_theme link shortener as it's prone to crashing on Salt docs
-try:
-    import pydata_sphinx_theme.short_link
-
-    def _no_op_run(self, **kwargs):
-        pass
-
-    pydata_sphinx_theme.short_link.ShortenLinkTransform.run = _no_op_run
-except ImportError:
-    pass
-
-# Manual mock for 'cgi' module which was removed in Python 3.13
-# This is required because some Salt modules import it at the top level,
-# and autodoc_mock_imports is sometimes too late or insufficient.
-import unittest.mock
-
-sys.modules["cgi"] = unittest.mock.MagicMock()
-
-
-# Patch urllib3 if it's available, as it has its own unsafe URL parsing
-def _patch_urllib3(module):
-    try:
-        _original_parse_url = module.util.url.parse_url
-
-        def _safe_parse_url(url):
-            try:
-                return _original_parse_url(url)
-            except (ValueError, AttributeError):
-                log.debug("urllib3 detected malformed URL: %s", url)
-                # Return a safe dummy Url object
-                return module.util.url.Url(path=url)
-
-        module.util.url.parse_url = _safe_parse_url
-    except (ImportError, AttributeError):
-        pass
-
-
-try:
-    import urllib3
-
-    _patch_urllib3(urllib3)
-except ImportError:
-    pass
-
-try:
-    import requests.packages.urllib3 as requests_urllib3
-
-    _patch_urllib3(requests_urllib3)
-except (ImportError, AttributeError):
-    pass
 
 import pathlib
 import re
@@ -310,11 +235,11 @@ def _safe_parse_url(url):
             ", ".join(_missing_deps),
         )
     else:
-        # For HTML/full builds, log info that docs may be incomplete
-        log.info(
+        # For HTML/full builds, warn that docs may be incomplete
+        log.warning(
             "\n"
             "=" * 70 + "\n"
-            "INFO: Missing optional dependencies for full documentation build:\n"
+            "WARNING: Missing dependencies for full documentation build:\n"
             "  %s\n\n"
             "Autodoc will use mocked modules. Documentation will be generated but\n"
             "may be incomplete or show incorrect type hints.\n\n"
@@ -569,15 +494,11 @@ class ReleasesTree(TocTree):
     option_spec = dict(TocTree.option_spec)
 
     def run(self):
-        try:
-            rst = super().run()
-            if rst and rst[0] and rst[0][0] and "entries" in rst[0][0]:
-                entries = rst[0][0]["entries"][:]
-                entries.sort(key=_normalize_version, reverse=True)
-                rst[0][0]["entries"][:] = entries
-            return rst
-        except (AttributeError, KeyError, IndexError, TypeError):
-            return super().run()
+        rst = super().run()
+        entries = rst[0][0]["entries"][:]
+        entries.sort(key=_normalize_version, reverse=True)
+        rst[0][0]["entries"][:] = entries
+        return rst
 
 
 def copy_release_templates_pre(app):

salt/modules/file.py

@@ -1979,7 +1979,7 @@ def line(
     indent=True,
 ):
     # pylint: disable=W1401
-    r"""
+    """
     .. versionadded:: 2015.8.0
 
     Line-focused editing of a file.

salt/modules/gem.py

@@ -96,11 +96,11 @@ def install(
         Include pre-releases in the available versions
     :param proxy: string : None
         Use the specified HTTP proxy server for all outgoing traffic.
-        Format: ``http://hostname:port``
+        Format: http://hostname[:port]
 
     source : None
         Use the specified HTTP gem source server to download gem.
-        Format: ``http://hostname:port``
+        Format: http://hostname[:port]
 
     CLI Example:
 

salt/states/gem.py

@@ -78,11 +78,11 @@ def installed(
 
     proxy : None
         Use the specified HTTP proxy server for all outgoing traffic.
-        Format: ``http://hostname:port``
+        Format: http://hostname[:port]
 
     source : None
         Use the specified HTTP gem source server to download gem.
-        Format: ``http://hostname:port``
+        Format: http://hostname[:port]
     """
     ret = {"name": name, "result": None, "comment": "", "changes": {}}
     if ruby is not None and not (

salt/states/mysql_grants.py

@@ -1,4 +1,4 @@
-r"""
+"""
 Management of MySQL grants (user permissions)
 =============================================
 

salt/transport/zeromq.py

@@ -518,7 +518,7 @@ def __init__(self, opts, addr, linger=0, io_loop=None):
         :param dict opts: The salt opts dictionary
         :param str addr: The interface IP address to bind to
         :param int linger: The number of seconds to linger on a ZMQ socket. See
-                           http://api.zeromq.org/2-1:zmq-setsockopt ``[ZMQ_LINGER]``
+                           http://api.zeromq.org/2-1:zmq-setsockopt [ZMQ_LINGER]
         :param IOLoop io_loop: A Tornado IOLoop event scheduler [tornado.ioloop.IOLoop]
         """
         self.opts = opts