diff options
| author | Felix Fontein <felix@fontein.de> | 2019-04-16 18:37:28 +0200 |
|---|---|---|
| committer | Alicia Cozine <879121+acozine@users.noreply.github.com> | 2019-04-16 11:37:28 -0500 |
| commit | 395d4710658070bcf20b9636f00072869f47ba10 (patch) | |
| tree | 43928c407b4f3a79e1a6013be009b797e240548d | |
| parent | 272dceef4258fdfdc90281ce1d0b02236f16a797 (diff) | |
| download | ansible-395d4710658070bcf20b9636f00072869f47ba10.tar.gz | |
Docs: adding stub page for module/plugin aliases (#54448)
* Adding stub pages for deprecated module/plugin aliases.
| -rwxr-xr-x | docs/bin/plugin_formatter.py | 25 | ||||
| -rw-r--r-- | docs/templates/plugin_deprecation_stub.rst.j2 | 18 |
2 files changed, 43 insertions, 0 deletions
diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index 3fb093fd9b..b136af5985 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 0000000000..5156f0bd96 --- /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. |