diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index 5df8b3d86e0..330a7540ab8 100755 --- a/docs/bin/plugin_formatter.py +++ b/docs/bin/plugin_formatter.py @@ -85,6 +85,28 @@ pp = PrettyPrinter() display = Display() +# kludge_ns gives us a kludgey way to set variables inside of loops that need to be visible outside +# the loop. We can get rid of this when we no longer need to build docs with less than Jinja-2.10 +# http://jinja.pocoo.org/docs/2.10/templates/#assignments +# With Jinja-2.10 we can use jinja2's namespace feature, restoring the namespace template portion +# of: fa5c0282a4816c4dd48e80b983ffc1e14506a1f5 +NS_MAP = {} + + +def to_kludge_ns(key, value): + NS_MAP[key] = value + return "" + + +def from_kludge_ns(key): + return NS_MAP[key] + + +# The max filter was added in Jinja2-2.10. Until we can require that version, use this +def do_max(seq): + return max(seq) + + def rst_ify(text): ''' convert symbols like I(this is in italics) to valid restructured text ''' @@ -298,6 +320,14 @@ def jinja2_environment(template_dir, typ, plugin_type): trim_blocks=True) env.globals['xline'] = rst_xline + # Can be removed (and template switched to use namespace) when we no longer need to build + # with - {# Pre-compute the nesting depth to allocate columns #} - {% set ns = namespace(maxdepth=1) %} - {% for key, value in options|dictsort recursive %} - {% set ns.maxdepth = [loop.depth, ns.maxdepth] | max %} - {% if value.suboptions %} - {% if value.suboptions.items %} - @{ loop(value.suboptions.items()) }@ - {% elif value.suboptions[0].items %} - @{ loop(value.suboptions[0].items()) }@ - {% endif %} - {% endif %} - {% endfor %} - {# Header of the documentation #} + {# Pre-compute the nesting depth to allocate columns -#} + @{ to_kludge_ns('maxdepth', 1) -}@ + {% for key, value in options|dictsort recursive -%} + @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@ + {% if value.suboptions -%} + {% if value.suboptions.items -%} + @{ loop(value.suboptions.items()) -}@ + {% elif value.suboptions[0].items -%} + @{ loop(value.suboptions[0].items()) -}@ + {% endif -%} + {% endif -%} + {% endfor -%} + {# Header of the documentation -#} - Parameter + Parameter Choices/Defaults {% if plugin_type != 'module' %} Configuration @@ -116,7 +116,7 @@ Parameters {% endfor %} {# parameter name with required and/or introduced label #} - + @{ key }@ {% if value.get('required', False) %}
required
{% endif %} {% if value.version_added %}
(added in @{value.version_added}@)
{% endif %} @@ -246,19 +246,19 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a {# Pre-compute the nesting depth to allocate columns #} - {% set ns = namespace(maxdepth=1) %} + @{ to_kludge_ns('maxdepth', 1) -}@ {% for key, value in returnfacts|dictsort recursive %} - {% set ns.maxdepth = [loop.depth, ns.maxdepth] | max %} - {% if value.contains %} - {% if value.contains.items %} - @{ loop(value.contains.items()) }@ - {% elif value.contains[0].items %} - @{ loop(value.contains[0].items()) }@ - {% endif %} - {% endif %} - {% endfor %} + @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@ + {% if value.contains -%} + {% if value.contains.items -%} + @{ loop(value.contains.items()) -}@ + {% elif value.contains[0].items -%} + @{ loop(value.contains[0].items()) -}@ + {% endif -%} + {% endif -%} + {% endfor -%} - + @@ -267,7 +267,7 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a {% for i in range(1, loop.depth) %} {% endfor %} - @@ -317,19 +317,19 @@ Common return values are documented :ref:`here `, the foll .. raw:: html
FactFact Returned Description
+ @{ key }@
@{ value.type }@
- {% set ns = namespace(maxdepth=1) %} - {% for key, value in returndocs|dictsort recursive %} - {% set ns.maxdepth = [loop.depth, ns.maxdepth] | max %} - {% if value.contains %} - {% if value.contains.items %} - @{ loop(value.contains.items()) }@ - {% elif value.contains[0].items %} - @{ loop(value.contains[0].items()) }@ - {% endif %} - {% endif %} - {% endfor %} + @{ to_kludge_ns('maxdepth', 1) -}@ + {% for key, value in returndocs|dictsort recursive -%} + @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@ + {% if value.contains -%} + {% if value.contains.items -%} + @{ loop(value.contains.items()) -}@ + {% elif value.contains[0].items -%} + @{ loop(value.contains[0].items()) -}@ + {% endif -%} + {% endif -%} + {% endfor -%} - + @@ -338,7 +338,7 @@ Common return values are documented :ref:`here `, the foll {% for i in range(1, loop.depth) %} {% endfor %} -
KeyKey Returned Description
  + @{ key }@
@{ value.type }@