Plugin/module docs: parse return values, add collection names in them (version_added_collection), and format them nicely in ansible-doc (#69796)

* Tag return value docs if they are a dict (and not str/None).

* Try to parse return docs as YAML.

* Properly dump return values in ansible-doc.

* Adjust plugin formatter.

* Add changelog fragment.

* Don't add 'default' for return values.

* Fix plugin_formatter.

* Only try to parse return docs if they are still a string.

* Add tests.

* Warn if RETURN cannot be parsed.

* Adjust tests. Also test for warning.

* if -> elif (otherwise EXAMPLE will be parsed too).

* Always parse return documentation, and fail if it is invalid YAML.

* Polishing.

* Mostly re-enable ansible-doc tests.

Listing from the local collection seems to be somewhat broken. I assume this
is why the test was disabled.

* Lint and make tests work with Python 2.

* Keep FQCNs in plugins (not modules), i.e. restore previous state.

8 files changed, 178 insertions, 14 deletions

diff --git a/test/integration/targets/ansible-doc/aliases b/test/integration/targets/ansible-doc/aliases
index 268da2c702..a6dafcf8cd 100644
--- a/test/integration/targets/ansible-doc/aliases
+++ b/test/integration/targets/ansible-doc/aliases
@@ -1,2 +1 @@
 shippable/posix/group1
-disabled
diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py
index ccb33b04dd..2ff181ab3b 100644
--- a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py
+++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py
@@ -2,7 +2,7 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = '''
-    vars: noop_vars_plugin
+    vars: testns.testcol.noop_vars_plugin
     short_description: Do NOT load host and group vars
     description: don't test loading host and group vars from a collection
     options:
diff --git a/test/integration/targets/ansible-doc/library/test_docs_returns.py b/test/integration/targets/ansible-doc/library/test_docs_returns.py
new file mode 100644
index 0000000000..77c1376453
--- /dev/null
+++ b/test/integration/targets/ansible-doc/library/test_docs_returns.py
@@ -0,0 +1,56 @@
+#!/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
+'''
+
+EXAMPLES = '''
+'''
+
+RETURN = '''
+z_last:
+    description: A last result.
+    type: str
+    returned: success
+
+m_middle:
+    description:
+        - This should be in the middle.
+        - Has some more data
+    type: dict
+    returned: success and 1st of month
+    contains:
+        suboption:
+            description: A suboption.
+            type: str
+            choices: [ARF, BARN, c_without_capital_first_letter]
+
+a_first:
+    description: A first result.
+    type: str
+    returned: success
+'''
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(),
+    )
+
+    module.exit_json()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/test/integration/targets/ansible-doc/library/test_docs_returns_broken.py b/test/integration/targets/ansible-doc/library/test_docs_returns_broken.py
new file mode 100644
index 0000000000..d6d62643f0
--- /dev/null
+++ b/test/integration/targets/ansible-doc/library/test_docs_returns_broken.py
@@ -0,0 +1,40 @@
+#!/usr/bin/python
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: test_docs_returns_broken
+short_description: Test module
+description:
+    - Test module
+author:
+    - Ansible Core Team
+'''
+
+EXAMPLES = '''
+'''
+
+RETURN = '''
+test:
+    description: A test return value.
+   type: str
+
+broken_key: [
+'''
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(),
+    )
+
+    module.exit_json()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/test/integration/targets/ansible-doc/runme.sh b/test/integration/targets/ansible-doc/runme.sh
index 84a69ee103..7cc6bfe449 100755
--- a/test/integration/targets/ansible-doc/runme.sh
+++ b/test/integration/targets/ansible-doc/runme.sh
@@ -12,18 +12,13 @@ current_out="$(ansible-doc --playbook-dir ./ testns.testcol.fakemodule)"
 expected_out="$(cat fakemodule.output)"
 test "$current_out" == "$expected_out"
 
-# test module docs from collection
-current_out="$(ansible-doc --playbook-dir ./ test_docs_suboptions)"
-expected_out="$(cat test_docs_suboptions.output)"
-test "$current_out" == "$expected_out"
-
 # test listing diff plugin types from collection
 for ptype in cache inventory lookup vars
 do
 	# each plugin type adds 1 from collection
-	pre=$(ansible-doc -l -t ${ptype}|wc -l)
-	post=$(ansible-doc -l -t ${ptype} --playbook-dir ./|wc -l)
-	test "$pre" -eq $((post - 1))
+	# FIXME pre=$(ansible-doc -l -t ${ptype}|wc -l)
+	# FIXME post=$(ansible-doc -l -t ${ptype} --playbook-dir ./|wc -l)
+	# FIXME test "$pre" -eq $((post - 1))
 
 	# ensure we ONLY list from the collection
 	justcol=$(ansible-doc -l -t ${ptype} --playbook-dir ./ testns.testcol|wc -l)
diff --git a/test/integration/targets/ansible-doc/test.yml b/test/integration/targets/ansible-doc/test.yml
index b0e04d918f..e03fb49a48 100644
--- a/test/integration/targets/ansible-doc/test.yml
+++ b/test/integration/targets/ansible-doc/test.yml
@@ -3,6 +3,46 @@
   environment:
     ANSIBLE_LIBRARY: "{{ playbook_dir }}/library"
   tasks:
+    - name: module with suboptions
+      command: ansible-doc test_docs_suboptions
+      register: result
+      ignore_errors: true
+
+    - set_fact:
+        actual_output: >-
+          {{ result.stdout | regex_replace('^(> [A-Z_]+ +\().+library/([a-z_]+.py)\)$', '\1library/\2)', multiline=true) }}
+        expected_output: "{{ lookup('file', 'test_docs_suboptions.output') }}"
+
+    - assert:
+        that:
+          - result is succeeded
+          - actual_output == expected_output
+
+    - name: module with return docs
+      command: ansible-doc test_docs_returns
+      register: result
+      ignore_errors: true
+
+    - set_fact:
+        actual_output: >-
+          {{ result.stdout | regex_replace('^(> [A-Z_]+ +\().+library/([a-z_]+.py)\)$', '\1library/\2)', multiline=true) }}
+        expected_output: "{{ lookup('file', 'test_docs_returns.output') }}"
+
+    - assert:
+        that:
+          - result is succeeded
+          - actual_output == expected_output
+
+    - name: module with broken return docs
+      command: ansible-doc test_docs_returns_broken
+      register: result
+      ignore_errors: true
+
+    - assert:
+        that:
+          - result is failed
+          - '"ERROR! module test_docs_returns_broken missing documentation (or could not parse documentation)" in result.stderr'
+
     - name: non-existent module
       command: ansible-doc test_does_not_exist
       register: result
diff --git a/test/integration/targets/ansible-doc/test_docs_returns.output b/test/integration/targets/ansible-doc/test_docs_returns.output
new file mode 100644
index 0000000000..9fbbc8c7f4
--- /dev/null
+++ b/test/integration/targets/ansible-doc/test_docs_returns.output
@@ -0,0 +1,37 @@
+> TEST_DOCS_RETURNS    (library/test_docs_returns.py)
+
+        Test module
+
+AUTHOR: Ansible Core Team
+
+EXAMPLES:
+
+
+
+
+RETURN VALUES:
+- a_first
+        A first result.
+
+        returned: success
+        type: str
+
+- m_middle
+        This should be in the middle.
+        Has some more data
+
+        returned: success and 1st of month
+        type: dict
+
+        CONTAINS:
+
+        - suboption
+            A suboption.
+            (Choices: ARF, BARN, c_without_capital_first_letter)
+            type: str
+
+- z_last
+        A last result.
+
+        returned: success
+        type: str
diff --git a/test/integration/targets/ansible-doc/test_docs_suboptions.output b/test/integration/targets/ansible-doc/test_docs_suboptions.output
index fb2a993f23..52b51d9d27 100644
--- a/test/integration/targets/ansible-doc/test_docs_suboptions.output
+++ b/test/integration/targets/ansible-doc/test_docs_suboptions.output
@@ -1,4 +1,4 @@
-> TEST_DOCS_SUBOPTIONS    (/home/felix/projects/code/github-cloned/ansible/test/integration/targets/ansible-doc/library/test_docs_suboptions.py)
+> TEST_DOCS_SUBOPTIONS    (library/test_docs_suboptions.py)
 
         Test module
 
@@ -41,6 +41,3 @@ EXAMPLES:
 
 
 
-
-RETURN VALUES:
-