diff --git a/changelogs/fragments/70046-ansible-doc-description-crash.yml b/changelogs/fragments/70046-ansible-doc-description-crash.yml new file mode 100644 index 00000000000..2220fb981ab --- /dev/null +++ b/changelogs/fragments/70046-ansible-doc-description-crash.yml @@ -0,0 +1,2 @@ +bugfixes: +- "ansible-doc - improve error message in text formatter when ``description`` is missing for a (sub-)option or a return value or its ``contains`` (https://github.com/ansible/ansible/pull/70046)." diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index 0572ec9d59c..cfb38f82fdf 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -526,6 +526,8 @@ class DocCLI(CLI): text.append("%s%s %s" % (base_indent, opt_leadin, o)) + if 'description' not in opt: + raise AnsibleError("All (sub-)options and return values must have a 'description' field") if isinstance(opt['description'], list): for entry_idx, entry in enumerate(opt['description'], 1): if not isinstance(entry, string_types): diff --git a/test/integration/targets/ansible-doc/library/test_docs_missing_description.py b/test/integration/targets/ansible-doc/library/test_docs_missing_description.py new file mode 100644 index 00000000000..6ed41836b0b --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_missing_description.py @@ -0,0 +1,40 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: test_docs_returns +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +options: + test: + type: str +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict( + test=dict(type='str'), + ), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/test.yml b/test/integration/targets/ansible-doc/test.yml index e03fb49a48e..a077a9941ac 100644 --- a/test/integration/targets/ansible-doc/test.yml +++ b/test/integration/targets/ansible-doc/test.yml @@ -3,6 +3,18 @@ environment: ANSIBLE_LIBRARY: "{{ playbook_dir }}/library" tasks: + - name: module with missing description return docs + command: ansible-doc test_docs_missing_description + register: result + ignore_errors: true + + - assert: + that: + - result is failed + - | + "ERROR! Unable to retrieve documentation from 'test_docs_missing_description' due to: All (sub-)options and return values must have a 'description' field" + in result.stderr + - name: module with suboptions command: ansible-doc test_docs_suboptions register: result