Improve/fix jinja2 templates (#373)

* Improve/fix jinja2 templates.

* Work around Python 3.6 issues.

src/antsibull/data/docsite/macros/parameters.rst.j2

@@ -1,7 +1,7 @@
-{% from 'macros/deprecates.rst.j2' import in_rst as deprecates_rst %}
-{% from 'macros/deprecates.rst.j2' import in_html as deprecates_html %}
+{% from 'macros/deprecates.rst.j2' import in_rst as deprecates_rst with context %}
+{% from 'macros/deprecates.rst.j2' import in_html as deprecates_html with context %}
 
-{% macro in_rst(elements, plugin_name, plugin_type, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='') %}
+{% macro in_rst(elements, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='') %}
 .. rst-class:: ansible-option-table
 
 .. list-table::
@@ -166,7 +166,7 @@
 
 {##################################################################################################################}
 
-{% macro in_html(elements, plugin_name, plugin_type, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='') %}
+{% macro in_html(elements, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='') %}
 .. raw:: html
 
   <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">

src/antsibull/data/docsite/macros/returnvalues.rst.j2

@@ -1,4 +1,4 @@
-{% macro in_rst(elements, plugin_name, plugin_type) %}
+{% macro in_rst(elements) %}
 .. rst-class:: ansible-option-table
 
 .. list-table::
@@ -91,7 +91,7 @@
 
 {##################################################################################################################}
 
-{% macro in_html(elements, plugin_name, plugin_type) %}
+{% macro in_html(elements) %}
 .. raw:: html
 
   <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">

src/antsibull/data/docsite/plugin.rst.j2

@@ -1,7 +1,7 @@
-{% from 'macros/parameters.rst.j2' import in_rst as parameters_rst %}
-{% from 'macros/parameters.rst.j2' import in_html as parameters_html %}
-{% from 'macros/returnvalues.rst.j2' import in_rst as return_docs_rst %}
-{% from 'macros/returnvalues.rst.j2' import in_html as return_docs_html %}
+{% from 'macros/parameters.rst.j2' import in_rst as parameters_rst with context %}
+{% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %}
+{% from 'macros/returnvalues.rst.j2' import in_rst as return_docs_rst with context %}
+{% from 'macros/returnvalues.rst.j2' import in_html as return_docs_html with context %}
 .. Document meta
 
 :orphan:
@@ -166,9 +166,9 @@ Parameters
 ----------
 
 {%   if use_html_blobs %}
-@{     parameters_html(doc['options'], plugin_type, plugin_name, suboption_key='suboptions') }@
+@{     parameters_html(doc['options'], suboption_key='suboptions') }@
 {%   else %}
-@{     parameters_rst(doc['options'], plugin_type, plugin_name, suboption_key='suboptions') }@
+@{     parameters_rst(doc['options'], suboption_key='suboptions') }@
 {%   endif %}
 {% endif %}
 
@@ -315,9 +315,9 @@ Returned Facts
 Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.
 
 {%   if use_html_blobs %}
-@{     return_docs_html(returnfacts, plugin_name, plugin_type) }@
+@{     return_docs_html(returnfacts) }@
 {%   else %}
-@{     return_docs_rst(returnfacts, plugin_name, plugin_type) }@
+@{     return_docs_rst(returnfacts) }@
 {%   endif %}
 {% endif %}
 
@@ -329,9 +329,9 @@ Return Values
 Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this @{ plugin_type }@:
 
 {%   if use_html_blobs %}
-@{     return_docs_html(returndocs, plugin_name, plugin_type) }@
+@{     return_docs_html(returndocs) }@
 {%   else %}
-@{     return_docs_rst(returndocs, plugin_name, plugin_type) }@
+@{     return_docs_rst(returndocs) }@
 {%   endif %}
 {% endif %}
 

src/antsibull/data/docsite/role.rst.j2

@@ -1,5 +1,5 @@
-{% from 'macros/parameters.rst.j2' import in_rst as parameters_rst %}
-{% from 'macros/parameters.rst.j2' import in_html as parameters_html %}
+{% from 'macros/parameters.rst.j2' import in_rst as parameters_rst with context %}
+{% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %}
 .. Document meta
 
 :orphan:
@@ -125,9 +125,9 @@ Parameters
 ^^^^^^^^^^
 
 {%     if use_html_blobs %}
-@{       parameters_html(ep_doc['options'], plugin_type, plugin_name, suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__') }@
+@{       parameters_html(ep_doc['options'], suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__') }@
 {%     else %}
-@{       parameters_rst(ep_doc['options'], plugin_type, plugin_name, suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__') }@
+@{       parameters_rst(ep_doc['options'], suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__') }@
 {%     endif %}
 {%   endif %}
 

src/antsibull/jinja2/filters.py

@@ -8,6 +8,8 @@
 from html import escape as html_escape
 from urllib.parse import quote
 
+import typing as t
+
 from jinja2.runtime import Undefined
 
 from ..logging import log
@@ -52,7 +54,7 @@ def html_ify(text):
     return text
 
 
-def documented_type(text):
+def documented_type(text) -> str:
     ''' Convert any python type to a type for documentation '''
 
     if isinstance(text, Undefined):
@@ -78,38 +80,38 @@ def do_max(seq):
 # https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#character-level-inline-markup-1
 # for further information.
 
-def _rst_ify_italic(m):
+def _rst_ify_italic(m: 're.Match') -> str:
     return f"\\ :emphasis:`{rst_escape(m.group(1), escape_ending_whitespace=True)}`\\ "
 
 
-def _rst_ify_bold(m):
+def _rst_ify_bold(m: 're.Match') -> str:
     return f"\\ :strong:`{rst_escape(m.group(1), escape_ending_whitespace=True)}`\\ "
 
 
-def _rst_ify_module(m):
+def _rst_ify_module(m: 're.Match') -> str:
     fqcn = '{0}.{1}.{2}'.format(m.group(1), m.group(2), m.group(3))
     return f"\\ :ref:`{rst_escape(fqcn)} <ansible_collections.{fqcn}_module>`\\ "
 
 
-def _escape_url(url):
+def _escape_url(url: str) -> str:
     # We include '<>[]{}' in safe to allow urls such as 'https://<HOST>:[PORT]/v{version}/' to
     # remain unmangled by percent encoding
     return quote(url, safe=':/#?%<>[]{}')
 
 
-def _rst_ify_link(m):
+def _rst_ify_link(m: 're.Match') -> str:
     return f"\\ `{rst_escape(m.group(1))} <{_escape_url(m.group(2))}>`__\\ "
 
 
-def _rst_ify_url(m):
+def _rst_ify_url(m: 're.Match') -> str:
     return f"\\ {_escape_url(m.group(1))}\\ "
 
 
-def _rst_ify_ref(m):
+def _rst_ify_ref(m: 're.Match') -> str:
     return f"\\ :ref:`{rst_escape(m.group(1))} <{m.group(2)}>`\\ "
 
 
-def _rst_ify_const(m):
+def _rst_ify_const(m: 're.Match') -> str:
     # Escaping does not work in double backticks, so we use the :literal: role instead
     return f"\\ :literal:`{rst_escape(m.group(1), escape_ending_whitespace=True)}`\\ "
 
@@ -135,7 +137,7 @@ def rst_ify(text):
     return text
 
 
-def rst_escape(value, escape_ending_whitespace=False):
+def rst_escape(value: t.Any, escape_ending_whitespace=False) -> str:
     ''' make sure value is converted to a string, and RST special characters are escaped '''
 
     if not isinstance(value, str):