From d7e847c1909e454bd8a823869e0b5bdddff1dae1 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 25 Dec 2021 12:19:21 +0100 Subject: [PATCH] Improve/fix jinja2 templates (#373) * Improve/fix jinja2 templates. * Work around Python 3.6 issues. --- .../data/docsite/macros/parameters.rst.j2 | 8 +++---- .../data/docsite/macros/returnvalues.rst.j2 | 4 ++-- src/antsibull/data/docsite/plugin.rst.j2 | 20 ++++++++--------- src/antsibull/data/docsite/role.rst.j2 | 8 +++---- src/antsibull/jinja2/filters.py | 22 ++++++++++--------- 5 files changed, 32 insertions(+), 30 deletions(-) diff --git a/src/antsibull/data/docsite/macros/parameters.rst.j2 b/src/antsibull/data/docsite/macros/parameters.rst.j2 index 40116e14..98d306a0 100644 --- a/src/antsibull/data/docsite/macros/parameters.rst.j2 +++ b/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 diff --git a/src/antsibull/data/docsite/macros/returnvalues.rst.j2 b/src/antsibull/data/docsite/macros/returnvalues.rst.j2 index a94557d9..4b9ac96b 100644 --- a/src/antsibull/data/docsite/macros/returnvalues.rst.j2 +++ b/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
diff --git a/src/antsibull/data/docsite/plugin.rst.j2 b/src/antsibull/data/docsite/plugin.rst.j2 index 9f305b17..db3e14f9 100644 --- a/src/antsibull/data/docsite/plugin.rst.j2 +++ b/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 `, 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 %} diff --git a/src/antsibull/data/docsite/role.rst.j2 b/src/antsibull/data/docsite/role.rst.j2 index 50337d1a..59129999 100644 --- a/src/antsibull/data/docsite/role.rst.j2 +++ b/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 %} diff --git a/src/antsibull/jinja2/filters.py b/src/antsibull/jinja2/filters.py index 86fcb6cc..3d177f6e 100644 --- a/src/antsibull/jinja2/filters.py +++ b/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)} `\\ " -def _escape_url(url): +def _escape_url(url: str) -> str: # We include '<>[]{}' in safe to allow urls such as 'https://:[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):