From 7242cf67b60941c91211af1bf4870ace4df403db Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Wed, 20 Nov 2024 21:13:54 +0100
Subject: [PATCH] Consider action plugin redirects.

---
 changelogs/fragments/360-action-modules.yml |  6 ++++
 src/antsibull_docs/docs_parsing/routing.py  | 37 ++++++++++++++++-----
 2 files changed, 35 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/fragments/360-action-modules.yml

diff --git a/changelogs/fragments/360-action-modules.yml b/changelogs/fragments/360-action-modules.yml
new file mode 100644
index 00000000..f28a18e2
--- /dev/null
+++ b/changelogs/fragments/360-action-modules.yml
@@ -0,0 +1,6 @@
+bugfixes:
+  - "Also consider action plugin redirects/deprecations in runtime metadata for modules,
+     since for users there is no difference. Also ``ansible.builtin.yum`` only has a action 
+     plugin redirect to ``ansible.builtin.dnf``, so this is needed to ensure that a stub
+     page generated for ``ansible.builtin.yum``
+     (https://github.com/ansible-community/antsibull-docs/pull/360)."
diff --git a/src/antsibull_docs/docs_parsing/routing.py b/src/antsibull_docs/docs_parsing/routing.py
index 8da11195..92dbb2ad 100644
--- a/src/antsibull_docs/docs_parsing/routing.py
+++ b/src/antsibull_docs/docs_parsing/routing.py
@@ -44,6 +44,8 @@
     "community.network",
 )
 
+_DOCUMENTABLE_PLUGINS_WITH_ACTION = frozenset(tuple(DOCUMENTABLE_PLUGINS) + ("action",))
+
 
 def calculate_plugin_fqcns(
     collection_name: str, src_basename: str, dst_basename: str, rel_path: str
@@ -242,7 +244,7 @@ def _add_symlink_redirects(
     collection_metadata: AnsibleCollectionMetadata,
     plugin_routing_out: dict[str, dict[str, dict[str, t.Any]]],
 ) -> None:
-    for plugin_type in DOCUMENTABLE_PLUGINS:
+    for plugin_type in _DOCUMENTABLE_PLUGINS_WITH_ACTION:
         directory_name = "modules" if plugin_type == "module" else plugin_type
         directory_path = os.path.join(
             collection_metadata.path, "plugins", directory_name
@@ -265,7 +267,7 @@ def _add_core_symlink_redirects(
     collection_metadata: AnsibleCollectionMetadata,
     plugin_routing_out: dict[str, dict[str, dict[str, t.Any]]],
 ) -> None:
-    for plugin_type in DOCUMENTABLE_PLUGINS:
+    for plugin_type in _DOCUMENTABLE_PLUGINS_WITH_ACTION:
         directory_name = (
             "modules"
             if plugin_type == "module"
@@ -284,6 +286,23 @@ def _add_core_symlink_redirects(
                 plugin_type_routing[redirect_name]["redirect"] = redirect_dst
 
 
+def _merge_action_into_modules(
+    plugin_routing_out: dict[str, dict[str, dict[str, t.Any]]]
+) -> None:
+    """
+    Merge 'action' routing info into 'modules' routing info.
+
+    Entries in 'action' trump over the corresponding entries in 'modules'
+    when resolving actions, which is what modules look like to users.
+    """
+    action_routing = plugin_routing_out.pop("action")
+    module_routing = plugin_routing_out["module"]
+    for plugin_name, plugin_data in action_routing.items():
+        if plugin_name not in module_routing:
+            module_routing[plugin_name] = {}
+        module_routing[plugin_name].update(plugin_data)
+
+
 async def load_collection_routing(
     collection_name: str, collection_metadata: AnsibleCollectionMetadata
 ) -> dict[str, dict[str, dict[str, t.Any]]]:
@@ -293,7 +312,7 @@ async def load_collection_routing(
     meta_runtime = load_meta_runtime(collection_name, collection_metadata)
     plugin_routing_out: dict[str, dict[str, dict[str, t.Any]]] = {}
     plugin_routing_in = meta_runtime.get("plugin_routing") or {}
-    for plugin_type in DOCUMENTABLE_PLUGINS:
+    for plugin_type in _DOCUMENTABLE_PLUGINS_WITH_ACTION:
         plugin_type_id = "modules" if plugin_type == "module" else plugin_type
         plugin_type_routing = plugin_routing_in.get(plugin_type_id) or {}
         plugin_routing_out[plugin_type] = {
@@ -301,17 +320,19 @@ async def load_collection_routing(
             for plugin_name, plugin_record in plugin_type_routing.items()
         }
 
+    # TODO collapse action + modules
+
     if collection_name == "ansible.builtin":
         # ansible-core has a special directory structure we currently do not want
         # (or need) to handle
         _add_core_symlink_redirects(collection_metadata, plugin_routing_out)
-        return plugin_routing_out
-
-    _add_symlink_redirects(collection_name, collection_metadata, plugin_routing_out)
+    else:
+        _add_symlink_redirects(collection_name, collection_metadata, plugin_routing_out)
 
-    if collection_name in COLLECTIONS_WITH_FLATMAPPING:
-        remove_flatmapping_artifacts(plugin_routing_out)
+        if collection_name in COLLECTIONS_WITH_FLATMAPPING:
+            remove_flatmapping_artifacts(plugin_routing_out)
 
+    _merge_action_into_modules(plugin_routing_out)
     return plugin_routing_out