From 205ca648bf4e80736a4324c0521488e09c49c62e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20Sj=C3=B6gren?= Date: Thu, 3 Jul 2025 17:26:09 +0200 Subject: [PATCH] ansible-doc: print where the description is missing (#85320) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ansible-doc: print where the description is missing Signed-off-by: Thomas Sjögren Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> --- .../ansible-doc-description-verbosity.yml | 2 ++ lib/ansible/cli/doc.py | 2 +- .../roles/test_role4/meta/argument_specs.yml | 34 +++++++++++++++++++ .../roles/test_role4/meta/main.yml | 10 ++++++ test/integration/targets/ansible-doc/runme.sh | 7 ++-- 5 files changed, 52 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/ansible-doc-description-verbosity.yml create mode 100644 test/integration/targets/ansible-doc/roles/test_role4/meta/argument_specs.yml create mode 100644 test/integration/targets/ansible-doc/roles/test_role4/meta/main.yml diff --git a/changelogs/fragments/ansible-doc-description-verbosity.yml b/changelogs/fragments/ansible-doc-description-verbosity.yml new file mode 100644 index 00000000000..7c000d995db --- /dev/null +++ b/changelogs/fragments/ansible-doc-description-verbosity.yml @@ -0,0 +1,2 @@ +minor_changes: + - ansible-doc - Return a more verbose error message when the ``description`` field is missing. diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 0319e51d09e..6b3c27e3408 100755 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -1265,7 +1265,7 @@ class DocCLI(CLI, RoleMixin): # description is specifically formatted and can either be string or list of strings if 'description' not in opt: - raise AnsibleError("All (sub-)options and return values must have a 'description' field") + raise AnsibleError("All (sub-)options and return values must have a 'description' field", obj=o) text.append('') # TODO: push this to top of for and sort by size, create indent on largest key? diff --git a/test/integration/targets/ansible-doc/roles/test_role4/meta/argument_specs.yml b/test/integration/targets/ansible-doc/roles/test_role4/meta/argument_specs.yml new file mode 100644 index 00000000000..5908f30aba2 --- /dev/null +++ b/test/integration/targets/ansible-doc/roles/test_role4/meta/argument_specs.yml @@ -0,0 +1,34 @@ +--- +argument_specs: + main: + short_description: test_role4 from roles subdir + description: + - In to am attended desirous raptures B(declared) diverted confined at. Collected instantly remaining + up certainly to C(necessary) as. Over walk dull into son boy door went new. + - At or happiness commanded daughters as. Is I(handsome) an declared at received in extended vicinity + subjects. Into miss on he over been late pain an. Only week bore boy what fat case left use. Match round + scale now style far times. Your me past an much. + author: + - John Doe (@john) + - Jane Doe (@jane) + attributes: + diff_mode: + description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode + support: partial + details: Not all modules used support this + options: + myopt1: + description: + - First option. + type: "str" + required: true + + myopt2: + type: "int" + default: 8000 + + myopt3: + description: + - Third option. + type: "bool" + default: false diff --git a/test/integration/targets/ansible-doc/roles/test_role4/meta/main.yml b/test/integration/targets/ansible-doc/roles/test_role4/meta/main.yml new file mode 100644 index 00000000000..26d1c2fc038 --- /dev/null +++ b/test/integration/targets/ansible-doc/roles/test_role4/meta/main.yml @@ -0,0 +1,10 @@ +# This meta/main.yml exists to test that it is NOT read, with preference being +# given to the meta/argument_specs.yml file. This spec contains an additional +# entry point that the argument_specs.yml does not. If this file # were read, +# the additional entrypoints would show up in --list output, breaking # tests. +--- +argument_specs: + main: + short_description: test_role4 from roles subdir + holden: + short_description: Rocinante pilot diff --git a/test/integration/targets/ansible-doc/runme.sh b/test/integration/targets/ansible-doc/runme.sh index adeb7a30ade..701d9086795 100755 --- a/test/integration/targets/ansible-doc/runme.sh +++ b/test/integration/targets/ansible-doc/runme.sh @@ -138,7 +138,7 @@ test "$output" -eq 4 echo "testing standalone roles" # Include normal roles (no collection filter) output=$(ansible-doc -t role -l --playbook-dir . | wc -l) -test "$output" -eq 8 +test "$output" -eq 11 echo "testing role precedence" # Test that a role in the playbook dir with the same name as a role in the @@ -288,5 +288,8 @@ echo "test 'sidecar' for no extension module with .py doc" echo "test 'sidecar' for no extension module with .yml doc" [ "$(ansible-doc -M ./library -l ansible.legacy |grep -v 'UNDOCUMENTED' |grep -c facts_one)" == "1" ] -echo "Test j2 plugins get jinja2 instead of path" +echo "test j2 plugins get jinja2 instead of path" ansible-doc -t filter map 2>&1 |grep "${GREP_OPTS[@]}" '(Jinja2)' + +echo "test missing description in test_role4 argument spec" +ansible-doc -t role -r ./roles test_role4 2>&1 >/dev/null | grep -q 'Error extracting role docs from '\''test_role4'\'': All (sub-)options and return values must have a '\''description'\'' field'