Use antsibull-docs-parser to render semantic markup.

Author: felixfontein

.config/dictionary.txt

@@ -22,6 +22,7 @@ nthhost
 ospfv
 slaac
 # Python packages
+antsibull
 argcomplete
 redbaron
 ruamel

.pre-commit-config.yaml

@@ -67,6 +67,7 @@ repos:
       - id: pylint
         additional_dependencies:
           - ansible-core
+          - antsibull-docs-parser
           - pyyaml
           - redbaron
           - ruamel.yaml

collection_prep/jinja_utils.py

@@ -1,23 +1,19 @@
 """Utilities for jinja2."""
-import re
 
-from html import escape as html_escape
 
 from ansible.module_utils._text import to_text
 from ansible.module_utils.six import string_types
+from antsibull_docs_parser import dom
+from antsibull_docs_parser.html import to_html_plain
+from antsibull_docs_parser.parser import Context
+from antsibull_docs_parser.parser import parse
+from antsibull_docs_parser.rst import to_rst_plain
 from jinja2.runtime import Undefined
+from jinja2.utils import pass_context
 
 
 NS_MAP = {}
 
-_ITALIC = re.compile(r"I\(([^)]+)\)")
-_BOLD = re.compile(r"B\(([^)]+)\)")
-_MODULE = re.compile(r"M\(([^)]+)\)")
-_URL = re.compile(r"U\(([^)]+)\)")
-_LINK = re.compile(r"L\(([^)]+), *([^)]+)\)")
-_CONST = re.compile(r"C\(([^)]+)\)")
-_RULER = re.compile(r"HORIZONTALLINE")
-
 
 def to_kludge_ns(key, value):
     """Save a value for later use.
@@ -39,40 +35,50 @@ def from_kludge_ns(key):
     return NS_MAP[key]
 
 
-def html_ify(text):
+def get_context(j2_context):
+    """Create parser context from Jinja2 context.
+
+    :param j2_context: The Jinja2 context
+    :return: A parser context
+    """
+    params = {}
+    plugin_fqcn = j2_context.get("module")
+    plugin_type = j2_context.get("plugin_type")
+    if plugin_fqcn is not None and plugin_type is not None:
+        params["current_plugin"] = dom.PluginIdentifier(fqcn=plugin_fqcn, type=plugin_type)
+    return Context(**params)
+
+
+@pass_context
+def html_ify(j2_context, text):
     """Convert symbols like I(this is in italics) to valid HTML.
 
+    :param j2_context: The Jinja2 context
     :param text: The text to transform
     :return: An HTML string of the formatted text
     """
     if not isinstance(text, string_types):
         text = to_text(text)
 
-    text = html_escape(text)
-    text = _ITALIC.sub(r"<em>\1</em>", text)
-    text = _BOLD.sub(r"<b>\1</b>", text)
-    text = _MODULE.sub(r"<span class='module'>\1</span>", text)
-    text = _URL.sub(r"<a href='\1'>\1</a>", text)
-    text = _LINK.sub(r"<a href='\2'>\1</a>", text)
-    text = _CONST.sub(r"<code>\1</code>", text)
-    text = _RULER.sub(r"<hr/>", text)
+    paragraphs = parse(text, get_context(j2_context))
+    text = to_html_plain(paragraphs, par_start="", par_end="")
 
     return text.strip()
 
 
-def rst_ify(text):
+@pass_context
+def rst_ify(j2_context, text):
     """Convert symbols like I(this is in italics) to valid restructured text.
 
+    :param j2_context: The Jinja2 context
     :param text: The text to transform
     :return: An RST string of the formatted text
     """
-    text = _ITALIC.sub(r"*\1*", text)
-    text = _BOLD.sub(r"**\1**", text)
-    text = _MODULE.sub(r":ref:`\1 <\1_module>`", text)
-    text = _LINK.sub(r"`\1 <\2>`_", text)
-    text = _URL.sub(r"\1", text)
-    text = _CONST.sub(r"``\1``", text)
-    text = _RULER.sub(r"------------", text)
+    if not isinstance(text, string_types):
+        text = to_text(text)
+
+    paragraphs = parse(text, get_context(j2_context))
+    text = to_rst_plain(paragraphs)
 
     return text
 

requirements.txt

@@ -1,3 +1,4 @@
 ansible-core
 redbaron
 ruamel.yaml
+antsibull-docs-parser >= 1.0.0, < 2.0.0