mirror of https://github.com/ansible/ansible.git
WIP - Fix ansible-doc bugs and add integration tests. (#62461)
* Add integration tests for ansible-doc. * Enable tests that now pass * Cleanup processing of plugin docs * Mostly separate the steps of processing plugin docs 1) Acquire source data 2) Transform and calculate additonal data 3) Format data for output 4) Output data format_plugin_doc() is still mixing transformation and formatting but that should be fixed in a devel-only change * Raise exceptions in _get_plugin_doc() on errors. * Remove check to exclude on blacklisted extensions. We already request only .py files * If there is no DOCUMENTATION entry in the plugin, raise an exception from _get_plugin_doc(). Everywhere we use _get_plugin_doc(), this is treated as an error * If there is no ANSIBLE_METADATA raise an exception as well as displaying of docs assumes that this has been set. * If there is neither DOCUMENTATION nor ANSIBLE_METADATA, warn about the lack of METADATA and error on the lack of DOCUMENTATION. Lack of DOCUMENTATION is more important so it is what the user should see. * Add a few special cases for backwards compat. These should probably be made errors in 2.10: * no docs but has metadata shows no documentation rather than an error * empty plugin file shows no doumentation rather than an error * Simplify backwards compatibility logic.pull/62470/head
parent
b68f5b406a
commit
3b86dc3e12
@ -0,0 +1 @@
|
||||
shippable/posix/group1
|
@ -0,0 +1 @@
|
||||
not_empty # avoid empty empty hosts list warning without defining explicit localhost
|
@ -0,0 +1,39 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': ['stableinterface'],
|
||||
'supported_by': 'core'}
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
module: test_docs
|
||||
short_description: Test module
|
||||
description:
|
||||
- Test module
|
||||
author:
|
||||
- Ansible Core Team
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
'''
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,35 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
module: test_docs_no_metadata
|
||||
short_description: Test module
|
||||
description:
|
||||
- Test module
|
||||
author:
|
||||
- Ansible Core Team
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
'''
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,38 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'supported_by': 'core'}
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
module: test_docs_no_status
|
||||
short_description: Test module
|
||||
description:
|
||||
- Test module
|
||||
author:
|
||||
- Ansible Core Team
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
'''
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,39 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': 1,
|
||||
'supported_by': 'core'}
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
module: test_docs_non_iterable_status
|
||||
short_description: Test module
|
||||
description:
|
||||
- Test module
|
||||
author:
|
||||
- Ansible Core Team
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
'''
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,39 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': ['removed'],
|
||||
'supported_by': 'core'}
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
module: test_docs_removed_status
|
||||
short_description: Test module
|
||||
description:
|
||||
- Test module
|
||||
author:
|
||||
- Ansible Core Team
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
'''
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,23 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': ['stableinterface'],
|
||||
'supported_by': 'core'}
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,18 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,22 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'supported_by': 'core'}
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,23 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': 1,
|
||||
'supported_by': 'core'}
|
||||
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(),
|
||||
)
|
||||
|
||||
module.exit_json()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
@ -0,0 +1,15 @@
|
||||
#!/usr/bin/python
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': ['removed'],
|
||||
'supported_by': 'core'}
|
||||
|
||||
|
||||
from ansible.module_utils.common.removed import removed_module
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
removed_module(removed_in='2.9')
|
@ -0,0 +1,4 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -eux
|
||||
ansible-playbook test.yml -i inventory "$@"
|
@ -0,0 +1,105 @@
|
||||
- hosts: localhost
|
||||
gather_facts: no
|
||||
environment:
|
||||
ANSIBLE_LIBRARY: "{{ playbook_dir }}/library"
|
||||
tasks:
|
||||
- name: non-existent module
|
||||
command: ansible-doc test_does_not_exist
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- '"[WARNING]: module test_does_not_exist not found in:" in result.stderr'
|
||||
|
||||
- name: documented module
|
||||
command: ansible-doc test_docs
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- '"WARNING" not in result.stderr'
|
||||
- '"TEST_DOCS " in result.stdout'
|
||||
- '"AUTHOR: Ansible Core Team" in result.stdout'
|
||||
|
||||
- name: documented module without metadata
|
||||
command: ansible-doc test_docs_no_metadata
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- '"WARNING" not in result.stderr'
|
||||
- '"TEST_DOCS_NO_METADATA " in result.stdout'
|
||||
- '"AUTHOR: Ansible Core Team" in result.stdout'
|
||||
|
||||
- name: documented module with no status in metadata
|
||||
command: ansible-doc test_docs_no_status
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- '"WARNING" not in result.stderr'
|
||||
- '"TEST_DOCS_NO_STATUS " in result.stdout'
|
||||
- '"AUTHOR: Ansible Core Team" in result.stdout'
|
||||
|
||||
- name: documented module with non-iterable status in metadata
|
||||
command: ansible-doc test_docs_non_iterable_status
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- '"WARNING" not in result.stderr'
|
||||
- '"TEST_DOCS_NON_ITERABLE_STATUS " in result.stdout'
|
||||
- '"AUTHOR: Ansible Core Team" in result.stdout'
|
||||
|
||||
- name: documented module with removed status
|
||||
command: ansible-doc test_docs_removed_status
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- '"WARNING" not in result.stderr'
|
||||
- '"TEST_DOCS_REMOVED_STATUS " in result.stdout'
|
||||
- '"AUTHOR: Ansible Core Team" in result.stdout'
|
||||
|
||||
- name: empty module
|
||||
command: ansible-doc test_empty
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- 'result.stdout == ""'
|
||||
- 'result.stderr == ""'
|
||||
|
||||
- name: module with no documentation
|
||||
command: ansible-doc test_no_docs
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- 'result.stdout == ""'
|
||||
- 'result.stderr == ""'
|
||||
|
||||
- name: module with no documentation and no metadata
|
||||
command: ansible-doc test_no_docs_no_metadata
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- 'result.stdout == ""'
|
||||
- 'result.stderr == ""'
|
||||
|
||||
- name: module with no documentation and no status in metadata
|
||||
command: ansible-doc test_no_docs_no_status
|
||||
ignore_errors: yes
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- 'result is failed'
|
||||
- '"ERROR! module test_no_docs_no_status missing documentation (or could not parse documentation): test_no_docs_no_status did not contain a DOCUMENTATION attribute" in result.stderr'
|
||||
|
||||
- name: module with no documentation and non-iterable status in metadata
|
||||
command: ansible-doc test_no_docs_non_iterable_status
|
||||
ignore_errors: yes
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- 'result is failed'
|
||||
- '"ERROR! module test_no_docs_non_iterable_status missing documentation (or could not parse documentation): test_no_docs_non_iterable_status did not contain a DOCUMENTATION attribute" in result.stderr'
|
||||
|
||||
- name: module with no documentation and removed status
|
||||
command: ansible-doc test_no_docs_removed_status
|
||||
register: result
|
||||
- assert:
|
||||
that:
|
||||
- '"[WARNING]: module test_no_docs_removed_status has been removed" in result.stderr'
|
Loading…
Reference in New Issue