Consider action plugin redirects (#360)

* Consider action plugin redirects.

* Add tests.

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)."

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,25 +312,27 @@ 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] = {
             f"{collection_name}.{plugin_name}": process_dates(plugin_record)
             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
 
 

tests/functional/baseline-default/collections/ns2/col/foo2_module.rst

@@ -54,6 +54,7 @@ Synopsis
 
 .. Aliases
 
+Aliases: foo_3_redirect, foo_4_redirect, foo_5_redirect
 
 .. Requirements
 

tests/functional/baseline-default/collections/ns2/col/foo_1_redirect_module.rst

@@ -0,0 +1,25 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_1_redirect_module:
+
+.. Title
+
+ns2.col.foo_1_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+    To use it in a playbook, specify: :code:`ns2.col.foo_1_redirect`.
+
+- This is a redirect to the :ansplugin:`ns2.col.foo module <ns2.col.foo#module>`.
+- This redirect does **not** work with Ansible 2.9.

tests/functional/baseline-default/collections/ns2/col/foo_2_redirect_module.rst

@@ -0,0 +1,25 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_2_redirect_module:
+
+.. Title
+
+ns2.col.foo_2_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+    To use it in a playbook, specify: :code:`ns2.col.foo_2_redirect`.
+
+- This is a redirect to the :ansplugin:`ns2.col.foo module <ns2.col.foo#module>`.
+- This redirect does **not** work with Ansible 2.9.

tests/functional/baseline-default/collections/ns2/col/foo_3_redirect_module.rst

@@ -0,0 +1,25 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_3_redirect_module:
+
+.. Title
+
+ns2.col.foo_3_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+    To use it in a playbook, specify: :code:`ns2.col.foo_3_redirect`.
+
+- This is a redirect to the :ansplugin:`ns2.col.foo2 module <ns2.col.foo2#module>`.
+- This redirect does **not** work with Ansible 2.9.

tests/functional/baseline-default/collections/ns2/col/foo_4_redirect_module.rst

@@ -0,0 +1,24 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_4_redirect_module:
+
+.. Title
+
+ns2.col.foo_4_redirect
+++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This plugin was part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+This module has been removed
+in version 2.0.0 of ns2.col.
+It is gone

tests/functional/baseline-default/collections/ns2/col/foo_5_redirect_module.rst

@@ -0,0 +1,27 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_5_redirect_module:
+
+.. Title
+
+ns2.col.foo_5_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+
+- This redirect has been **deprecated**. Please update your tasks to use the new name ``ns2.col.foo2`` instead.
+  It will be removed in version 5.0.0 of ns2.col.
+- This is a redirect to the :ansplugin:`ns2.col.foo2 module <ns2.col.foo2#module>`.
+- This redirect does **not** work with Ansible 2.9.
+- The collection contains the following information on this deprecation: It will be really gone

tests/functional/baseline-default/collections/ns2/col/foo_module.rst

@@ -59,7 +59,7 @@ Synopsis
 
 .. Aliases
 
-Aliases: foo_redirect
+Aliases: foo_1_redirect, foo_2_redirect, foo_redirect
 
 .. Requirements
 

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo2_module.rst

@@ -54,6 +54,7 @@ Synopsis
 
 .. Aliases
 
+Aliases: foo_3_redirect, foo_4_redirect, foo_5_redirect
 
 .. Requirements
 

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_1_redirect_module.rst

@@ -0,0 +1,25 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_1_redirect_module:
+
+.. Title
+
+ns2.col.foo_1_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+    To use it in a playbook, specify: :code:`ns2.col.foo_1_redirect`.
+
+- This is a redirect to the :ansplugin:`ns2.col.foo module <ns2.col.foo#module>`.
+- This redirect does **not** work with Ansible 2.9.

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_2_redirect_module.rst

@@ -0,0 +1,25 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_2_redirect_module:
+
+.. Title
+
+ns2.col.foo_2_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+    To use it in a playbook, specify: :code:`ns2.col.foo_2_redirect`.
+
+- This is a redirect to the :ansplugin:`ns2.col.foo module <ns2.col.foo#module>`.
+- This redirect does **not** work with Ansible 2.9.

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_3_redirect_module.rst

@@ -0,0 +1,25 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_3_redirect_module:
+
+.. Title
+
+ns2.col.foo_3_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+    To use it in a playbook, specify: :code:`ns2.col.foo_3_redirect`.
+
+- This is a redirect to the :ansplugin:`ns2.col.foo2 module <ns2.col.foo2#module>`.
+- This redirect does **not** work with Ansible 2.9.

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_4_redirect_module.rst

@@ -0,0 +1,24 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_4_redirect_module:
+
+.. Title
+
+ns2.col.foo_4_redirect
+++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This plugin was part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+This module has been removed
+in version 2.0.0 of ns2.col.
+It is gone

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_5_redirect_module.rst

@@ -0,0 +1,27 @@
+.. Document meta
+
+:orphan:
+
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
+.. Anchors
+
+.. _ansible_collections.ns2.col.foo_5_redirect_module:
+
+.. Title
+
+ns2.col.foo_5_redirect module
++++++++++++++++++++++++++++++
+
+.. Collection note
+
+.. note::
+    This redirect is part of the `ns2.col collection <https://galaxy.ansible.com/ui/repo/published/ns2/col/>`_ (version 2.1.0).
+
+
+- This redirect has been **deprecated**. Please update your tasks to use the new name ``ns2.col.foo2`` instead.
+  It will be removed in version 5.0.0 of ns2.col.
+- This is a redirect to the :ansplugin:`ns2.col.foo2 module <ns2.col.foo2#module>`.
+- This redirect does **not** work with Ansible 2.9.
+- The collection contains the following information on this deprecation: It will be really gone

tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_module.rst

@@ -59,7 +59,7 @@ Synopsis
 
 .. Aliases
 
-Aliases: foo_redirect
+Aliases: foo_1_redirect, foo_2_redirect, foo_redirect
 
 .. Requirements
 

tests/functional/baseline-no-indexes/collections/ns2/col/foo2_module.rst

@@ -51,6 +51,7 @@ Synopsis
 
 .. Aliases
 
+Aliases: foo_3_redirect, foo_4_redirect, foo_5_redirect
 
 .. Requirements