ansible-doc man formatter: fail with better error message when description isn't there (#70046) (#70485)

* ansible-doc man formatter: do not crash when description isn't there.
* Change to report a better error message when description is not there.
* Add test.

(cherry picked from commit 9164b96774)
This commit is contained in:
Felix Fontein 2020-07-17 21:44:03 +02:00 committed by GitHub
parent 422e976649
commit a5c0b11913
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 56 additions and 0 deletions

View file

@ -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)."

View file

@ -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):

View file

@ -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()

View file

@ -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