Improve error output when calls to ansible-doc or ansible --version fail

changelogs/fragments/223-ansible-doc-errors.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Improve error messages when calls to ``ansible-doc`` fail (https://github.com/ansible-community/antsibull-docs/pull/223)."

src/antsibull_docs/docs_parsing/ansible_doc.py

@@ -10,6 +10,8 @@
 import json
 import os
 import re
+import shlex
+import textwrap
 import typing as t
 from collections.abc import Mapping
 
@@ -87,10 +89,18 @@ async def _call_ansible_galaxy_collection_list(
     venv: VenvRunner | FakeVenvRunner,
     env: dict[str, str],
 ) -> Mapping[str, t.Any]:
-    p = await venv.async_log_run(
-        ["ansible-galaxy", "collection", "list", "--format", "json"],
-        env=env,
-    )
+    try:
+        p = await venv.async_log_run(
+            ["ansible-galaxy", "collection", "list", "--format", "json"],
+            env=env,
+        )
+    except CalledProcessError as exc:
+        if exc.returncode and exc.returncode > 0:
+            raise RuntimeError(
+                f"The command\n| {shlex.join(exc.cmd)}\nreturned exit status {exc.returncode}"
+                f" with error output:\n{textwrap.indent(exc.stderr, '| ')}"
+            ) from exc
+        raise
     return json.loads(_filter_non_json_lines(p.stdout)[0])
 
 
@@ -156,5 +166,6 @@ async def get_ansible_core_version(
         return PypiVer(metadata.version)
     except CalledProcessError as exc:
         raise ValueError(
-            f"Cannot retrieve ansible-core version from `ansible --version`: {exc}"
+            f"Cannot retrieve ansible-core version from `ansible --version`: {exc};"
+            f" error output:\n{textwrap.indent(exc.stderr, '| ')}"
         ) from exc

src/antsibull_docs/docs_parsing/ansible_doc_core_213.py

@@ -8,11 +8,14 @@
 from __future__ import annotations
 
 import json
+import shlex
+import textwrap
 import typing as t
 from collections.abc import Mapping, MutableMapping
 
 import semantic_version as semver
 from antsibull_core.logging import log
+from antsibull_core.subprocess_util import CalledProcessError
 from antsibull_core.vendored.json_utils import _filter_non_json_lines
 from packaging.version import Version as PypiVer
 
@@ -33,10 +36,24 @@ async def _call_ansible_doc(
     env: dict[str, str],
     *parameters: str,
 ) -> Mapping[str, t.Any]:
-    p = await venv.async_log_run(
-        ["ansible-doc", "-vvv", "--metadata-dump", "--no-fail-on-errors", *parameters],
-        env=env,
-    )
+    try:
+        p = await venv.async_log_run(
+            [
+                "ansible-doc",
+                "-vvv",
+                "--metadata-dump",
+                "--no-fail-on-errors",
+                *parameters,
+            ],
+            env=env,
+        )
+    except CalledProcessError as exc:
+        if exc.returncode and exc.returncode > 0:
+            raise RuntimeError(
+                f"The command\n| {shlex.join(exc.cmd)}\nreturned exit status {exc.returncode}"
+                f" with error output:\n{textwrap.indent(exc.stderr, '| ')}"
+            ) from exc
+        raise
     return json.loads(_filter_non_json_lines(p.stdout)[0])