From 395d4710658070bcf20b9636f00072869f47ba10 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Tue, 16 Apr 2019 18:37:28 +0200
Subject: [PATCH] Docs: adding stub page for module/plugin aliases (#54448)

* Adding stub pages for deprecated module/plugin aliases.
---
 docs/bin/plugin_formatter.py                  | 25 +++++++++++++++++++
 docs/templates/plugin_deprecation_stub.rst.j2 | 18 +++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 docs/templates/plugin_deprecation_stub.rst.j2

diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py
index 3fb093fd9b8..b136af59858 100755
--- a/docs/bin/plugin_formatter.py
+++ b/docs/bin/plugin_formatter.py
@@ -275,8 +275,11 @@ def get_plugin_info(module_dir, limit_to=None, verbose=False):
                 module = module.replace("_", "", 1)
                 aliases = module_info[source].get('aliases', set())
                 aliases.add(module)
+                aliases_deprecated = module_info[source].get('aliases_deprecated', set())
+                aliases_deprecated.add(module)
                 # In case we just created this via get()'s fallback
                 module_info[source]['aliases'] = aliases
+                module_info[source]['aliases_deprecated'] = aliases_deprecated
                 continue
             else:
                 # Handle deprecations
@@ -340,6 +343,7 @@ def get_plugin_info(module_dir, limit_to=None, verbose=False):
                                'source': os.path.relpath(module_path, module_dir),
                                'deprecated': deprecated,
                                'aliases': module_info[module].get('aliases', set()),
+                               'aliases_deprecated': module_info[module].get('aliases_deprecated', set()),
                                'metadata': metadata,
                                'doc': doc,
                                'examples': examples,
@@ -404,6 +408,7 @@ def jinja2_environment(template_dir, typ, plugin_type):
         env.filters['documented_type'] = documented_type
         env.tests['list'] = test_list
         templates['plugin'] = env.get_template('plugin.rst.j2')
+        templates['plugin_deprecation_stub'] = env.get_template('plugin_deprecation_stub.rst.j2')
 
         if plugin_type == 'module':
             name = 'modules'
@@ -570,6 +575,26 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi
 
         write_data(text, output_dir, outputname, module)
 
+        # Create deprecation stub pages for deprecated aliases
+        if module_map[module]['aliases']:
+            for alias in module_map[module]['aliases']:
+                if alias in module_map[module]['aliases_deprecated']:
+                    doc['alias'] = alias
+
+                    display.v('about to template %s (deprecation alias %s)' % (module, alias))
+                    display.vvvvv(pp.pformat(doc))
+                    try:
+                        text = templates['plugin_deprecation_stub'].render(doc)
+                    except Exception as e:
+                        display.warning(msg="Could not parse %s (deprecation alias %s) due to %s" % (module, alias, e))
+                        continue
+
+                    if LooseVersion(jinja2.__version__) < LooseVersion('2.10'):
+                        # jinja2 < 2.10's indent filter indents blank lines.  Cleanup
+                        text = re.sub(' +\n', '\n', text)
+
+                    write_data(text, output_dir, outputname, alias)
+
 
 def process_categories(plugin_info, categories, templates, output_dir, output_name, plugin_type):
     # For some reason, this line is changing plugin_info:
diff --git a/docs/templates/plugin_deprecation_stub.rst.j2 b/docs/templates/plugin_deprecation_stub.rst.j2
new file mode 100644
index 00000000000..5156f0bd96e
--- /dev/null
+++ b/docs/templates/plugin_deprecation_stub.rst.j2
@@ -0,0 +1,18 @@
+:source: @{ source }@
+
+{# avoids rST "isn't included in any toctree" errors for module docs #}
+:orphan:
+
+.. _@{ module }@_@{ plugin_type }@_alias_@{ alias }@:
+
+{% if short_description %}
+{%   set title = alias + ' -- ' + short_description | rst_ify %}
+{% else %}
+{%   set title = alias %}
+{% endif %}
+
+@{ title }@
+@{ '+' * title|length }@
+
+This is an alias for :ref:`@{ module }@ <@{ module }@_@{ plugin_type }@>`.
+This name has been **deprecated**. Please update your tasks to use the new name ``@{ module }@`` instead.