From 55e9e21dedeba7efa91f811624389d57fa969045 Mon Sep 17 00:00:00 2001
From: simonLeary42 <71396965+simonLeary42@users.noreply.github.com>
Date: Mon, 17 Feb 2025 16:12:14 -0500
Subject: [PATCH] better error message for malformed documentation (#84705)

No the file name that caused the error will be apparent
---------

Signed-off-by: Abhijeet Kasurde <Akasurde@redhat.com>
Co-authored-by: Abhijeet Kasurde <Akasurde@redhat.com>
---
 ...or-message-malformed-plugin-documentation.yml |  2 ++
 lib/ansible/plugins/loader.py                    |  6 +++++-
 .../ansible-doc/lookup_plugins/broken_docs.py    | 16 ++++++++++++++++
 test/integration/targets/ansible-doc/test.yml    | 10 ++++++++++
 4 files changed, 33 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/fragments/84705-error-message-malformed-plugin-documentation.yml
 create mode 100644 test/integration/targets/ansible-doc/lookup_plugins/broken_docs.py

diff --git a/changelogs/fragments/84705-error-message-malformed-plugin-documentation.yml b/changelogs/fragments/84705-error-message-malformed-plugin-documentation.yml
new file mode 100644
index 00000000000..488cf8bcccf
--- /dev/null
+++ b/changelogs/fragments/84705-error-message-malformed-plugin-documentation.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - improved error message for yaml parsing errors in plugin documentation
diff --git a/lib/ansible/plugins/loader.py b/lib/ansible/plugins/loader.py
index c24d0628231..2132b5f3d0f 100644
--- a/lib/ansible/plugins/loader.py
+++ b/lib/ansible/plugins/loader.py
@@ -16,6 +16,7 @@ import warnings
 from collections import defaultdict, namedtuple
 from importlib import import_module
 from traceback import format_exc
+from yaml.parser import ParserError
 
 import ansible.module_utils.compat.typing as t
 
@@ -407,7 +408,10 @@ class PluginLoader:
 
             # if type name != 'module_doc_fragment':
             if type_name in C.CONFIGURABLE_PLUGINS and not C.config.has_configuration_definition(type_name, name):
-                dstring = AnsibleLoader(getattr(module, 'DOCUMENTATION', ''), file_name=path).get_single_data()
+                try:
+                    dstring = AnsibleLoader(getattr(module, 'DOCUMENTATION', ''), file_name=path).get_single_data()
+                except ParserError as e:
+                    raise AnsibleError(f"plugin {name} has malformed documentation!") from e
 
                 # TODO: allow configurable plugins to use sidecar
                 # if not dstring:
diff --git a/test/integration/targets/ansible-doc/lookup_plugins/broken_docs.py b/test/integration/targets/ansible-doc/lookup_plugins/broken_docs.py
new file mode 100644
index 00000000000..7061dbd98f7
--- /dev/null
+++ b/test/integration/targets/ansible-doc/lookup_plugins/broken_docs.py
@@ -0,0 +1,16 @@
+# Copyright (c) 2022 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+
+DOCUMENTATION = """
+    name: broken_docs
+    -
+"""
+
+EXAMPLE = """
+"""
+
+RETURN = """
+"""
diff --git a/test/integration/targets/ansible-doc/test.yml b/test/integration/targets/ansible-doc/test.yml
index 0c3dcc0c22b..2046dfd7ecc 100644
--- a/test/integration/targets/ansible-doc/test.yml
+++ b/test/integration/targets/ansible-doc/test.yml
@@ -181,3 +181,13 @@
           - '"[DEPRECATION WARNING]" in result.stderr'
           - '"deprecated_with_adj_docs " in result.stdout'
           - '"AUTHOR: Ansible Core Team" in result.stdout'
+
+    - name: Handle plugin docs
+      debug:
+        msg: "{{ lookup('broken_docs') }}"
+      register: r
+      ignore_errors: yes
+
+    - assert:
+        that:
+          - "'plugin broken_docs has malformed documentation' in r.msg"