ansible-doc: improve version_added handling (#73602)

* Output version_added on top level, and improve version_added formatting

* Handle 'historical' version_added.

3 files changed, 112 insertions, 2 deletions

diff --git a/test/integration/targets/ansible-doc/fakemodule.output b/test/integration/targets/ansible-doc/fakemodule.output
index 01070fd50b..5548ad5ece 100644
--- a/test/integration/targets/ansible-doc/fakemodule.output
+++ b/test/integration/targets/ansible-doc/fakemodule.output
@@ -2,6 +2,8 @@
 
         this is a fake module
 
+ADDED IN: version 1.0.0 of testns.testcol
+
 OPTIONS (= is mandatory):
 
 - _notreal
@@ -12,5 +14,3 @@ OPTIONS (= is mandatory):
 AUTHOR: me
 
 SHORT_DESCIPTION: fake module
-
-VERSION_ADDED_COLLECTION: testns.testcol
diff --git a/test/integration/targets/ansible-doc/randommodule-text.output b/test/integration/targets/ansible-doc/randommodule-text.output
new file mode 100644
index 0000000000..24327a5955
--- /dev/null
+++ b/test/integration/targets/ansible-doc/randommodule-text.output
@@ -0,0 +1,105 @@
+> TESTNS.TESTCOL.RANDOMMODULE    (./collections/ansible_collections/testns/testcol/plugins/modules/randommodule.py)
+
+        A random module.
+
+ADDED IN: version 1.0.0 of testns.testcol
+
+DEPRECATED: 
+
+	Reason: Test deprecation
+	Will be removed in: Ansible 3.0.0
+	Alternatives: Use some other module
+
+
+OPTIONS (= is mandatory):
+
+- sub
+        Suboptions.
+        [Default: (null)]
+        set_via:
+          env:
+          - deprecated:
+              alternative: none
+              removed_in: 2.0.0
+              version: 2.0.0
+              why: Test deprecation
+            name: TEST_ENV
+        
+        type: dict
+
+        OPTIONS:
+
+        - subtest2
+            Another suboption.
+            [Default: (null)]
+            type: float
+            added in: version 1.1.0
+
+
+
+        SUBOPTIONS:
+
+        - subtest
+            A suboption.
+            [Default: (null)]
+            type: int
+            added in: version 1.1.0 of testns.testcol
+
+
+- test
+        Some text.
+        [Default: (null)]
+        type: str
+        added in: version 1.2.0 of testns.testcol
+
+
+- testcol2option
+        An option taken from testcol2
+        [Default: (null)]
+        type: str
+        added in: version 1.0.0 of testns.testcol2
+
+
+- testcol2option2
+        Another option taken from testcol2
+        [Default: (null)]
+        type: str
+
+
+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
+            added in: version 1.4.0 of testns.testcol
+
+
+- z_last
+        A last result.
+
+        returned: success
+        type: str
+        added in: version 1.3.0 of testns.testcol
+
diff --git a/test/integration/targets/ansible-doc/runme.sh b/test/integration/targets/ansible-doc/runme.sh
index 4f40d7c38d..4a6f6820bc 100755
--- a/test/integration/targets/ansible-doc/runme.sh
+++ b/test/integration/targets/ansible-doc/runme.sh
@@ -19,6 +19,11 @@ current_out="$(ansible-doc --playbook-dir ./ testns.testcol.fakemodule | sed '1
 expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.FAKEMODULE\).*(.*)$/\1/' fakemodule.output)"
 test "$current_out" == "$expected_out"
 
+# we use sed to strip the module path from the first line
+current_out="$(ansible-doc --playbook-dir ./ testns.testcol.randommodule | sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/')"
+expected_out="$(sed '1 s/\(^> TESTNS\.TESTCOL\.RANDOMMODULE\).*(.*)$/\1/' randommodule-text.output)"
+test "$current_out" == "$expected_out"
+
 # ensure we do work with valid collection name for list
 ansible-doc --list testns.testcol --playbook-dir ./ 2>&1 | grep -v "Invalid collection pattern"