From 2074dcab7eb3f5b39e0ee32e82d251e2aeac4ac9 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 8 Jun 2021 18:23:54 +0200 Subject: [PATCH] Add semantic markup support. --- .../list_of_collections_by_namespace.rst.j2 | 3 ++ antsibull/data/docsite/list_of_plugins.rst.j2 | 3 ++ .../data/docsite/plugin-deprecation.rst.j2 | 3 ++ antsibull/data/docsite/plugin-redirect.rst.j2 | 3 ++ .../data/docsite/plugin-tombstone.rst.j2 | 3 ++ antsibull/data/docsite/plugin.rst.j2 | 3 ++ .../data/docsite/plugins_by_collection.rst.j2 | 3 ++ antsibull/data/docsite/role.rst.j2 | 3 ++ antsibull/jinja2/filters.py | 28 ++++++++++++++++++- 9 files changed, 51 insertions(+), 1 deletion(-) diff --git a/antsibull/data/docsite/list_of_collections_by_namespace.rst.j2 b/antsibull/data/docsite/list_of_collections_by_namespace.rst.j2 index c8c8ef172..677a2c3c3 100644 --- a/antsibull/data/docsite/list_of_collections_by_namespace.rst.j2 +++ b/antsibull/data/docsite/list_of_collections_by_namespace.rst.j2 @@ -2,6 +2,9 @@ :orphan: {% endif %} +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + .. _list_of_collections_@{ namespace }@: {% set title = 'Collections in the ' ~ (namespace | title) ~ ' Namespace' | rst_ify -%} diff --git a/antsibull/data/docsite/list_of_plugins.rst.j2 b/antsibull/data/docsite/list_of_plugins.rst.j2 index dcefed989..4d482713c 100644 --- a/antsibull/data/docsite/list_of_plugins.rst.j2 +++ b/antsibull/data/docsite/list_of_plugins.rst.j2 @@ -1,5 +1,8 @@ :orphan: +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + .. _list_of_@{ plugin_type }@_plugins: {% if plugin_type == 'module' %} diff --git a/antsibull/data/docsite/plugin-deprecation.rst.j2 b/antsibull/data/docsite/plugin-deprecation.rst.j2 index 5156f0bd9..92069bd54 100644 --- a/antsibull/data/docsite/plugin-deprecation.rst.j2 +++ b/antsibull/data/docsite/plugin-deprecation.rst.j2 @@ -3,6 +3,9 @@ {# avoids rST "isn't included in any toctree" errors for module docs #} :orphan: +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + .. _@{ module }@_@{ plugin_type }@_alias_@{ alias }@: {% if short_description %} diff --git a/antsibull/data/docsite/plugin-redirect.rst.j2 b/antsibull/data/docsite/plugin-redirect.rst.j2 index 50148dcad..47262bed4 100644 --- a/antsibull/data/docsite/plugin-redirect.rst.j2 +++ b/antsibull/data/docsite/plugin-redirect.rst.j2 @@ -2,6 +2,9 @@ :orphan: +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + .. Anchors .. _ansible_collections.@{plugin_name}@_@{plugin_type}@: diff --git a/antsibull/data/docsite/plugin-tombstone.rst.j2 b/antsibull/data/docsite/plugin-tombstone.rst.j2 index 6f4cc686a..dc546e1d9 100644 --- a/antsibull/data/docsite/plugin-tombstone.rst.j2 +++ b/antsibull/data/docsite/plugin-tombstone.rst.j2 @@ -2,6 +2,9 @@ :orphan: +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + .. Anchors .. _ansible_collections.@{plugin_name}@_@{plugin_type}@: diff --git a/antsibull/data/docsite/plugin.rst.j2 b/antsibull/data/docsite/plugin.rst.j2 index 3917b1a3c..b1e2488bb 100644 --- a/antsibull/data/docsite/plugin.rst.j2 +++ b/antsibull/data/docsite/plugin.rst.j2 @@ -2,6 +2,9 @@ :orphan: +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + {# If we can put together source and github repo, we could make the Edit me of github button work. See meta.get("source") in Ansible's docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html for more information diff --git a/antsibull/data/docsite/plugins_by_collection.rst.j2 b/antsibull/data/docsite/plugins_by_collection.rst.j2 index dedf0ea03..4dfaad6c4 100644 --- a/antsibull/data/docsite/plugins_by_collection.rst.j2 +++ b/antsibull/data/docsite/plugins_by_collection.rst.j2 @@ -2,6 +2,9 @@ :orphan: {% endif %} +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + .. _plugins_in_@{collection_name}@: @{collection_name.title()}@ diff --git a/antsibull/data/docsite/role.rst.j2 b/antsibull/data/docsite/role.rst.j2 index c026255ce..f1272e23e 100644 --- a/antsibull/data/docsite/role.rst.j2 +++ b/antsibull/data/docsite/role.rst.j2 @@ -2,6 +2,9 @@ :orphan: +.. |equalsign| unicode:: 0x3D .. equal sign + :trim: + {# If we can put together source and github repo, we could make the Edit me of github button work. See meta.get("source") in Ansible's docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html for more information diff --git a/antsibull/jinja2/filters.py b/antsibull/jinja2/filters.py index 61a6589a7..e52a0a30b 100644 --- a/antsibull/jinja2/filters.py +++ b/antsibull/jinja2/filters.py @@ -19,13 +19,24 @@ _ITALIC = re.compile(r"\bI\(([^)]+)\)") _BOLD = re.compile(r"\bB\(([^)]+)\)") _MODULE = re.compile(r"\bM\(([^)]+)\)") +_PLUGIN = re.compile(r"\bP\(([^#)]+)#([a-z]+)\)") _URL = re.compile(r"\bU\(([^)]+)\)") _LINK = re.compile(r"\bL\(([^)]+), *([^)]+)\)") _REF = re.compile(r"\bR\(([^)]+), *([^)]+)\)") _CONST = re.compile(r"\bC\(([^)]+)\)") +_SEM_OPTION_NAME = re.compile(r"\bO\(([^)]+)\)") +_SEM_OPTION_VALUE = re.compile(r"\bV\(([^)]+)\)") +_SEM_ENV_VARIABLE = re.compile(r"\bE\(([^)]+)\)") _RULER = re.compile(r"\bHORIZONTALLINE\b") +def _option_name_html(matcher): + parts = matcher.group(1).split('=', 1) + if len(parts) == 1: + return f'{parts[0]}' + return f'{parts[0]}={parts[1]}' + + def html_ify(text): ''' convert symbols like I(this is in italics) to valid HTML ''' @@ -36,11 +47,15 @@ def html_ify(text): text = html_escape(text) text, _counts['italic'] = _ITALIC.subn(r"\1", text) text, _counts['bold'] = _BOLD.subn(r"\1", text) - text, _counts['module'] = _MODULE.subn(r"\1", text) + text, _counts['module'] = _MODULE.subn(r"\1", text) + text, _counts['plugin'] = _PLUGIN.subn(r"\1", text) text, _counts['url'] = _URL.subn(r"\1", text) text, _counts['ref'] = _REF.subn(r"\1", text) text, _counts['link'] = _LINK.subn(r"\1", text) text, _counts['const'] = _CONST.subn(r"\1", text) + text, _counts['option-name'] = _SEM_OPTION_NAME.subn(_option_name_html, text) + text, _counts['option-value'] = _SEM_OPTION_VALUE.subn(r"\1", text) + text, _counts['environment-var'] = _SEM_ENV_VARIABLE.subn(r"\1", text) text, _counts['ruler'] = _RULER.subn(r"
", text) text = text.strip() @@ -70,6 +85,13 @@ def do_max(seq): return max(seq) +def _option_name_rst(matcher): + parts = matcher.group(1).split('=', 1) + if len(parts) == 1: + return f'*{parts[0]}*' + return f'*{parts[0]}* |equalsign| ``{parts[1]}``' + + def rst_ify(text): ''' convert symbols like I(this is in italics) to valid restructured text ''' @@ -80,10 +102,14 @@ def rst_ify(text): text, _counts['italic'] = _ITALIC.subn(r"*\1*", text) text, _counts['bold'] = _BOLD.subn(r"**\1**", text) text, _counts['module'] = _MODULE.subn(r":ref:`\1 `", text) + text, _counts['plugin'] = _PLUGIN.subn(r":ref:`\1 `", text) text, _counts['url'] = _LINK.subn(r"`\1 <\2>`_", text) text, _counts['ref'] = _URL.subn(r"\1", text) text, _counts['link'] = _REF.subn(r":ref:`\1 <\2>`", text) text, _counts['const'] = _CONST.subn(r"``\1``", text) + text, _counts['option-name'] = _SEM_OPTION_NAME.subn(_option_name_rst, text) + text, _counts['option-value'] = _SEM_OPTION_VALUE.subn(r"``\1``", text) + text, _counts['environment-var'] = _SEM_ENV_VARIABLE.subn(r"``\1``", text) text, _counts['ruler'] = _RULER.subn(f"\n\n{'-' * 13}\n\n", text) flog.fields(counts=_counts).info('Number of macros converted to rst equivalents')