From 16f0b7461c1b76665d885da5bb06032fb112e1ff Mon Sep 17 00:00:00 2001
From: Paul Belanger <pabelanger@redhat.com>
Date: Wed, 17 Jun 2020 13:09:28 -0400
Subject: [PATCH] Support `removed_at_date` in ansible-doc (#70002) (#70015)

* 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>
(cherry picked from commit 9d6b0f2b03609037e58e9dc2fdf590c7ad7a9d10)
Signed-off-by: Paul Belanger <pabelanger@redhat.com>

Co-authored-by: Nilashish Chakraborty <nilashishchakraborty8@gmail.com>
---
 .../fragments/ansible-doc-remove_at_date.yaml |  2 +
 lib/ansible/cli/doc.py                        | 11 +++--
 .../library/test_docs_removed_precedence.py   | 40 +++++++++++++++++++
 test/integration/targets/ansible-doc/test.yml | 11 +++++
 4 files changed, 61 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/fragments/ansible-doc-remove_at_date.yaml
 create mode 100644 test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py

diff --git a/changelogs/fragments/ansible-doc-remove_at_date.yaml b/changelogs/fragments/ansible-doc-remove_at_date.yaml
new file mode 100644
index 00000000000..21254692aa2
--- /dev/null
+++ b/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. 
diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index f7878ff4e92..21064be39d8 100644
--- a/lib/ansible/cli/doc.py
+++ b/lib/ansible/cli/doc.py
@@ -611,9 +611,14 @@ class DocCLI(CLI):
         if 'deprecated' in doc and doc['deprecated'] is not None and len(doc['deprecated']) > 0:
             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")
diff --git a/test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py b/test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py
new file mode 100644
index 00000000000..3de1c6906c4
--- /dev/null
+++ b/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()
diff --git a/test/integration/targets/ansible-doc/test.yml b/test/integration/targets/ansible-doc/test.yml
index 4398752c407..f76430e08ab 100644
--- a/test/integration/targets/ansible-doc/test.yml
+++ b/test/integration/targets/ansible-doc/test.yml
@@ -103,3 +103,14 @@
     - assert:
         that:
           - '"[WARNING]: module test_no_docs_removed_status has been removed" in result.stderr'
+
+    - 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'