Support `removed_at_date` in ansible-doc (#70002)

* Support removed_at_date in ansible-doc

Signed-off-by: NilashishC <nilashishchakraborty8@gmail.com>

Changes:
  * ansible-doc does not support `removed_at_date` and assumes that
    deprecated dict will either have `removed_in` or `version`. This
    results in ansible-doc (and hence "sanity --test=ansible-doc")
    failing for modules having only `removed_at_date`.

  * This patch adds support for `removed_at_date` and also gives it
    precedence over `removed_in` or `version`.

* Add tests and changelog

Signed-off-by: NilashishC <nilashishchakraborty8@gmail.com>

changelogs/fragments/ansible-doc-remove_at_date.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- ansible-doc - Allow and give precedence to `removed_at_date` for deprecated modules. 

lib/ansible/cli/doc.py

@@ -617,9 +617,14 @@ class DocCLI(CLI):
         if doc.get('deprecated', False):
             text.append("DEPRECATED: \n")
             if isinstance(doc['deprecated'], dict):
-                if 'version' in doc['deprecated'] and 'removed_in' not in doc['deprecated']:
-                    doc['deprecated']['removed_in'] = doc['deprecated']['version']
-                text.append("\tReason: %(why)s\n\tWill be removed in: Ansible %(removed_in)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated'))
+                if 'removed_at_date' in doc['deprecated']:
+                    text.append(
+                        "\tReason: %(why)s\n\tWill be removed in a release after %(removed_at_date)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated')
+                    )
+                else:
+                    if 'version' in doc['deprecated'] and 'removed_in' not in doc['deprecated']:
+                        doc['deprecated']['removed_in'] = doc['deprecated']['version']
+                    text.append("\tReason: %(why)s\n\tWill be removed in: Ansible %(removed_in)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated'))
             else:
                 text.append("%s" % doc.pop('deprecated'))
             text.append("\n")

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

@@ -0,0 +1,40 @@
+#!/usr/bin/python
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: test_docs_removed_precedence
+short_description: Test module
+description:
+    - Test module
+author:
+    - Ansible Core Team
+deprecated:
+  alternative: new_module
+  why: Updated module released with more functionality
+  removed_at_date: '2022-06-01'
+  removed_in: '2.14'
+'''
+
+EXAMPLES = '''
+'''
+
+RETURN = '''
+'''
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(),
+    )
+
+    module.exit_json()
+
+
+if __name__ == '__main__':
+    main()

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

@@ -73,3 +73,14 @@
     - assert:
         that:
           - result is failed
+
+    - name: deprecated module with both removed date and version (date should get precedence)
+      command: ansible-doc test_docs_removed_precedence
+      register: result
+
+    - assert:
+        that:
+          - '"DEPRECATED" in result.stdout'
+          - '"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'