Ansible configuration: improve deprecation messages (#2823) (#2864)

* Improve config deprecation messages.

* Update formulations according to review comments.

(cherry picked from commit 768ed19)

Co-authored-by: Felix Fontein <[email protected]>

Author: patchback[bot]

docs/templates/config.rst.j2

@@ -157,10 +157,14 @@ you can use the command line utility mentioned above (`ansible-config`) to brows
        :Version Added: {{ini_map['version_added']}}
 {%         endif %}
 {%         if ini_map['deprecated'] %}
-       :Deprecated in: {{ini_map['deprecated']['version']}}
-       :Deprecated detail: {{ini_map['deprecated']['why']}}
+       :Note: This config setting is now deprecated and scheduled for removal.
 {%           if ini_map['deprecated']['alternatives'] %}
-       :Deprecated alternatives: {{ini_map['deprecated']['alternatives']}}
+              You should update to a current alternative.
+{%           endif %}
+       :Scheduled removal: {{ini_map['deprecated']['version']}}
+       :Deprecation reason: {{ini_map['deprecated']['why']}}
+{%           if ini_map['deprecated']['alternatives'] %}
+       :Current alternatives: {{ini_map['deprecated']['alternatives']}}
 {%           endif %}
 {%         endif %}
 {%       endfor %}
@@ -173,10 +177,14 @@ you can use the command line utility mentioned above (`ansible-config`) to brows
        :Version Added: {{env_var_map['version_added']}}
 {%         endif %}
 {%         if env_var_map['deprecated'] %}
-       :Deprecated in: {{env_var_map['deprecated']['version']}}
-       :Deprecated detail: {{env_var_map['deprecated']['why']}}
+       :Note: This environment variable is now deprecated and scheduled for removal.
 {%           if env_var_map['deprecated']['alternatives'] %}
-       :Deprecated alternatives: {{env_var_map['deprecated']['alternatives']}}
+              You should update to a current alternative.
+{%           endif %}
+       :Scheduled removal: {{env_var_map['deprecated']['version']}}
+       :Deprecation reason: {{env_var_map['deprecated']['why']}}
+{%           if env_var_map['deprecated']['alternatives'] %}
+       :Current alternatives: {{env_var_map['deprecated']['alternatives']}}
 {%           endif %}
 {%         endif %}
 {%       endfor %}
@@ -189,19 +197,27 @@ you can use the command line utility mentioned above (`ansible-config`) to brows
        :Version Added: {{a_var['version_added']}}
 {%       endif %}
 {%         if a_var['deprecated'] %}
-       :Deprecated in: {{a_var['deprecated']['version']}}
-       :Deprecated detail: {{a_Var['deprecated']['why']}}
+       :Note: This Ansible variable is now deprecated and scheduled for removal.
+{%           if a_var['deprecated']['alternatives'] %}
+              You should update to a current alternative.
+{%           endif %}
+       :Scheduled removal: {{a_var['deprecated']['version']}}
+       :Deprecation reason: {{a_Var['deprecated']['why']}}
 {%           if a_var['deprecated']['alternatives'] %}
-       :Deprecated alternatives: {{a_var['deprecated']['alternatives']}}
+       :Current alternatives: {{a_var['deprecated']['alternatives']}}
 {%           endif %}
 {%         endif %}
 {%       endfor %}
 {%     endif %}
 {%     if config['deprecated'] %}
-:Deprecated in: {{config['deprecated']['version']}}
-:Deprecated detail: {{config['deprecated']['why']}}
+:Note: This configuration is now deprecated and scheduled for removal.
+{%       if config['deprecated']['alternatives'] %}
+       You should update to a current alternative.
+{%       endif %}
+:Scheduled removal: {{config['deprecated']['version']}}
+:Deprecation reason: {{config['deprecated']['why']}}
 {%       if config['deprecated']['alternatives'] %}
-:Deprecated alternatives: {{config['deprecated']['alternatives']}}
+:Current alternatives: {{config['deprecated']['alternatives']}}
 {%       endif %}
 {%     endif %}
 
@@ -236,10 +252,14 @@ Other environment variables to configure plugins in collections can be found in
     :Version Added: {{env_var_map['version_added']}}
 {%       endif %}
 {%       if env_var_map['deprecated'] %}
-    :Deprecated in: {{env_var_map['deprecated']['version']}}
-    :Deprecated detail: {{env_var_map['deprecated']['why']}}
+    :Note: This environment variable is now deprecated and scheduled for removal.
+{%         if env_var_map['deprecated']['alternatives'] %}
+           You should update to a current alternative.
+{%         endif %}
+    :Scheduled removal: {{env_var_map['deprecated']['version']}}
+    :Deprecation reason: {{env_var_map['deprecated']['why']}}
 {%         if env_var_map['deprecated']['alternatives'] %}
-    :Deprecated alternatives: {{env_var_map['deprecated']['alternatives']}}
+    :Current alternatives: {{env_var_map['deprecated']['alternatives']}}
 {%         endif %}
 {%       endif %}