Add ansible-doc tests for documentation containing YAML anchors (#70436)

Co-authored-by: Tadej Borovšak <tadej.borovsak@xlab.si>

test/integration/targets/ansible-doc/library/test_docs_yaml_anchors.py

@@ -0,0 +1,71 @@
+#!/usr/bin/python
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: test_docs_yaml_anchors
+short_description: Test module with YAML anchors in docs
+description:
+    - Test module
+author:
+    - Ansible Core Team
+options:
+  at_the_top: &toplevel_anchor
+    description:
+        - Short desc
+    default: some string
+    type: str
+
+  last_one: *toplevel_anchor
+
+  egress:
+    description:
+        - Egress firewall rules
+    type: list
+    elements: dict
+    suboptions: &sub_anchor
+        port:
+            description:
+                - Rule port
+            type: int
+            required: true
+
+  ingress:
+    description:
+        - Ingress firewall rules
+    type: list
+    elements: dict
+    suboptions: *sub_anchor
+'''
+
+EXAMPLES = '''
+'''
+
+RETURN = '''
+'''
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            at_the_top=dict(type='str', default='some string'),
+            last_one=dict(type='str', default='some string'),
+            egress=dict(type='list', elements='dict', options=dict(
+                port=dict(type='int', required=True),
+            )),
+            ingress=dict(type='list', elements='dict', options=dict(
+                port=dict(type='int', required=True),
+            )),
+        ),
+    )
+
+    module.exit_json()
+
+
+if __name__ == '__main__':
+    main()

test/integration/targets/ansible-doc/test.yml

@@ -136,3 +136,14 @@
           - '"Reason: Updated module released with more functionality" in result.stdout'
           - '"Will be removed in a release after 2022-06-01" in result.stdout'
           - '"Alternatives: new_module" in result.stdout'
+
+    - name: documented module with YAML anchors
+      command: ansible-doc test_docs_yaml_anchors
+      register: result
+    - set_fact:
+        actual_output: >-
+          {{ result.stdout | regex_replace('^(> [A-Z_]+ +\().+library/([a-z_]+.py)\)$', '\1library/\2)', multiline=true) }}
+        expected_output: "{{ lookup('file', 'test_docs_yaml_anchors.output') }}"
+    - assert:
+        that:
+          - actual_output == expected_output

test/integration/targets/ansible-doc/test_docs_yaml_anchors.output

@@ -0,0 +1,49 @@
+> TEST_DOCS_YAML_ANCHORS    (library/test_docs_yaml_anchors.py)
+
+        Test module
+
+OPTIONS (= is mandatory):
+
+- at_the_top
+        Short desc
+        [Default: some string]
+        type: str
+
+- egress
+        Egress firewall rules
+        [Default: (null)]
+        elements: dict
+        type: list
+
+        SUBOPTIONS:
+
+        = port
+            Rule port
+
+            type: int
+
+- ingress
+        Ingress firewall rules
+        [Default: (null)]
+        elements: dict
+        type: list
+
+        SUBOPTIONS:
+
+        = port
+            Rule port
+
+            type: int
+
+- last_one
+        Short desc
+        [Default: some string]
+        type: str
+
+
+AUTHOR: Ansible Core Team
+
+EXAMPLES:
+
+
+