Deprecate HTML 4 support (#10843)

5 files changed, 30 insertions, 1 deletions

diff --git a/CHANGES b/CHANGES
index eb75defe4..637b6b618 100644
--- a/CHANGES
+++ b/CHANGES
@@ -14,6 +14,8 @@ Incompatible changes
 Deprecated
 ----------
 
+* #10843: Support for HTML 4 output. Patch by Adam Turner.
+
 Features added
 --------------
 
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 18b0e6d04..8c850ceb6 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - HTML 4 support
+     - 5.2
+     - 7.0
+     - N/A
+
    * - ``sphinx.util.path_stabilize``
      - 5.1
      - 7.0
diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index c75338d8f..e80ac3c7e 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -374,7 +374,7 @@ class StandaloneHTMLBuilder(Builder):
     @property
     def default_translator_class(self) -> Type[nodes.NodeVisitor]:  # type: ignore
         if self.config.html4_writer:
-            return HTMLTranslator
+            return HTMLTranslator  # RemovedInSphinx70Warning
         else:
             return HTML5Translator
 
@@ -1338,6 +1338,16 @@ def migrate_html_add_permalinks(app: Sphinx, config: Config) -> None:
         html_add_permalinks
     )
 
+
+def deprecate_html_4(_app: Sphinx, config: Config) -> None:
+    """Warn on HTML 4."""
+    # RemovedInSphinx70Warning
+    if config.html4_writer:
+        logger.warning(_('Support for emitting HTML 4 output is deprecated and '
+                         'will be removed in Sphinx 7. ("html4_writer=True '
+                         'detected in configuration options)'))
+
+
 # for compatibility
 import sphinxcontrib.serializinghtml  # NOQA
 
@@ -1414,6 +1424,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('config-inited', validate_html_static_path, priority=800)
     app.connect('config-inited', validate_html_logo, priority=800)
     app.connect('config-inited', validate_html_favicon, priority=800)
+    app.connect('config-inited', deprecate_html_4, priority=800)
     app.connect('builder-inited', validate_math_renderer)
     app.connect('html-page-context', setup_css_tag_helper)
     app.connect('html-page-context', setup_js_tag_helper)
diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py
index 1846dd675..48183204d 100644
--- a/sphinx/writers/html.py
+++ b/sphinx/writers/html.py
@@ -67,6 +67,7 @@ class HTMLWriter(Writer):
         self.clean_meta = ''.join(self.visitor.meta[2:])
 
 
+# RemovedInSphinx70Warning
 class HTMLTranslator(SphinxTranslator, BaseTranslator):
     """
     Our custom HTML translator.
diff --git a/tests/test_build_html.py b/tests/test_build_html.py
index 8fd83b438..c7d2daf47 100644
--- a/tests/test_build_html.py
+++ b/tests/test_build_html.py
@@ -131,6 +131,16 @@ def test_html4_output(app, status, warning):
     app.build()
 
 
+def test_html4_deprecation(make_app, tempdir):
+    (tempdir / 'conf.py').write_text('', encoding='utf-8')
+    app = make_app(
+        buildername='html',
+        srcdir=tempdir,
+        confoverrides={'html4_writer': True},
+    )
+    assert 'HTML 4 output is deprecated and will be removed' in app._warning.getvalue()
+
+
 @pytest.mark.parametrize("fname,expect", flat_dict({
     'images.html': [
         (".//img[@src='_images/img.png']", ''),