Deprecate --use-html-blobs

changelogs/fragments/217-deprecate-use-html-blobs.yml

@@ -0,0 +1,8 @@
+deprecated_features:
+  - "The ``--use-html-blobs`` feature that inserts HTML blobs for the options and return value
+     tables for the ``ansible-docsite`` output format is deprecated and will be removed soon.
+     The HTML tables cause several features to break, such as references to options and return
+     values. If you think this feature needs to stay, please create an issue in the `antsibull-docs
+     repository <https://github.com/ansible-community/antsibull-docs/issues/>`__ and provide
+     good reasons for it
+     (https://github.com/ansible-community/antsibull-docs/pull/217)."

src/antsibull_docs/cli/doc_commands/_build.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import asyncio
+import sys
 import textwrap
 import typing as t
 from collections.abc import MutableMapping
@@ -90,12 +91,20 @@ def _remove_collections(
 def _validate_options(
     collection_names: list[str] | None,
     exclude_collection_names: list[str] | None,
+    use_html_blobs: bool,
 ) -> None:
     if collection_names is not None and exclude_collection_names is not None:
         raise ValueError(
             "Cannot specify both collection_names and exclude_collection_names"
         )
 
+    if use_html_blobs:
+        print(
+            "WARNING: the use of --use-html-blobs is deprecated."
+            " This feature will be removed soon.",
+            file=sys.stderr,
+        )
+
 
 def generate_docs_for_all_collections(  # noqa: C901
     venv: VenvRunner | FakeVenvRunner,
@@ -153,7 +162,7 @@ def generate_docs_for_all_collections(  # noqa: C901
     flog = mlog.fields(func="generate_docs_for_all_collections")
     flog.notice("Begin")
 
-    _validate_options(collection_names, exclude_collection_names)
+    _validate_options(collection_names, exclude_collection_names, use_html_blobs)
 
     if collection_names is not None and "ansible.builtin" not in collection_names:
         exclude_collection_names = ["ansible.builtin"]

src/antsibull_docs/cli/doc_commands/plugin.py

@@ -52,6 +52,13 @@ def generate_plugin_docs(
 
     app_ctx = app_context.app_ctx.get()
 
+    if app_ctx.use_html_blobs:
+        print(
+            "WARNING: the use of --use-html-blobs is deprecated."
+            " This feature will be removed soon.",
+            file=sys.stderr,
+        )
+
     venv = FakeVenvRunner()
     venv_ansible_doc = venv.get_command("ansible-doc")
     venv_ansible_doc = venv_ansible_doc.bake("-vvv")

src/antsibull_docs/cli/doc_commands/sphinx_init.py

@@ -9,6 +9,7 @@
 
 import os
 import os.path
+import sys
 import typing as t
 
 from antsibull_core.logging import log
@@ -132,6 +133,13 @@ def site_init() -> int:
     extra_html_theme_options = split_kv(app_ctx.extra["extra_html_theme_options"])
     output_format = app_ctx.extra["output_format"]
 
+    if use_html_blobs:
+        print(
+            "WARNING: the use of --use-html-blobs is deprecated."
+            " This feature will be removed soon.",
+            file=sys.stderr,
+        )
+
     sphinx_theme = "sphinx_ansible_theme"
     sphinx_theme_package = "sphinx-ansible-theme >= 0.9.0"
     if app_ctx.extra["sphinx_theme"] != "sphinx-ansible-theme":