ansible-test action-plugin-docs sidecar (#83325)

Fix to have ansible-test sanity --test action-plugin-docs to check for
action plugin documentation inside a sidecar file rather than a Python
module.

changelogs/fragments/action-plugin-docs-sidecar.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- ansible-test action-plugin-docs - Fix to check for sidecar documentation for action plugins

test/integration/targets/ansible-test-sanity-action-plugin-docs/aliases

@@ -0,0 +1,4 @@
+shippable/posix/group3  # runs in the distro test containers
+shippable/generic/group1  # runs in the default test container
+context/controller
+needs/target/collection

test/integration/targets/ansible-test-sanity-action-plugin-docs/ansible_collections/ns/col/plugins/action/other.yml

@@ -0,0 +1 @@
+random: data

test/integration/targets/ansible-test-sanity-action-plugin-docs/ansible_collections/ns/col/plugins/action/with_py.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+from ansible.plugins.action import ActionBase
+
+
+class ActionModule(ActionBase):
+    def run(self, tmp, task_vars):
+        return {"changed": False}

test/integration/targets/ansible-test-sanity-action-plugin-docs/ansible_collections/ns/col/plugins/action/with_yaml.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+from ansible.plugins.action import ActionBase
+
+
+class ActionModule(ActionBase):
+    def run(self, tmp, task_vars):
+        return {"changed": False}

test/integration/targets/ansible-test-sanity-action-plugin-docs/ansible_collections/ns/col/plugins/action/with_yml.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+from ansible.plugins.action import ActionBase
+
+
+class ActionModule(ActionBase):
+    def run(self, tmp, task_vars):
+        return {"changed": False}

test/integration/targets/ansible-test-sanity-action-plugin-docs/ansible_collections/ns/col/plugins/modules/with_py.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+DOCUMENTATION = r"""
+---
+module: with_py
+short_description: Short description
+description: Long description
+options: {}
+author:
+  - Ansible Core Team (@ansible)
+"""
+
+EXAMPLES = r"""
+- name: Some example
+  ns.col.with_py:
+"""
+
+RETURNS = ""

test/integration/targets/ansible-test-sanity-action-plugin-docs/ansible_collections/ns/col/plugins/modules/with_yaml.yaml

@@ -0,0 +1,16 @@
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+DOCUMENTATION:
+  module: with_yaml
+  short_description: Short description
+  description: Long description
+  options: {}
+  author:
+    - Ansible Core Team (@ansible)
+
+EXAMPLES: |
+  - name: Some example
+    ns.col.with_yaml:
+
+RETURNS: {}

test/integration/targets/ansible-test-sanity-action-plugin-docs/ansible_collections/ns/col/plugins/modules/with_yml.yml

@@ -0,0 +1,16 @@
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+DOCUMENTATION:
+  module: with_yml
+  short_description: Short description
+  description: Long description
+  options: {}
+  author:
+    - Ansible Core Team (@ansible)
+
+EXAMPLES: |
+  - name: Some example
+    ns.col.with_yml:
+
+RETURNS: {}

test/integration/targets/ansible-test-sanity-action-plugin-docs/runme.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -eu
+
+source ../collection/setup.sh
+
+set -x
+
+ansible-test sanity --test action-plugin-docs --color "${@}"

test/lib/ansible_test/_util/controller/sanity/code-smell/action-plugin-docs.json

@@ -7,7 +7,9 @@
         "plugins/action/"
     ],
     "extensions": [
-        ".py"
+        ".py",
+        ".yml",
+        ".yaml"
     ],
     "output": "path-message"
 }

test/lib/ansible_test/_util/controller/sanity/code-smell/action-plugin-docs.py

@@ -28,13 +28,13 @@ def main():
             module_names.add(full_name)
 
     for path in paths:
-        full_name = get_full_name(path, action_prefixes)
+        full_name = get_full_name(path, action_prefixes, extensions=('.py',))
 
         if full_name and full_name not in module_names:
             print('%s: action plugin has no matching module to provide documentation' % path)
 
 
-def get_full_name(path, prefixes):
+def get_full_name(path: str, prefixes: dict[str, bool], extensions: tuple[str] | None = None) -> str | None:
     """Return the full name of the plugin at the given path by matching against the given path prefixes, or None if no match is found."""
     for prefix, flat in prefixes.items():
         if path.startswith(prefix):
@@ -45,13 +45,16 @@ def get_full_name(path, prefixes):
             else:
                 full_name = relative_path
 
-            full_name = os.path.splitext(full_name)[0]
+            full_name, file_ext = os.path.splitext(full_name)
 
             name = os.path.basename(full_name)
 
             if name == '__init__':
                 return None
 
+            if extensions and file_ext not in extensions:
+                return None
+
             if name.startswith('_'):
                 name = name[1:]