Add semantic markup support.

src/antsibull/jinja2/filters.py

@@ -22,13 +22,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'<em>{parts[0]}</em>'
+    return f"<em>{parts[0]}</em>=<code class='docutils literal notranslate'>{parts[1]}</code>"
+
+
 def html_ify(text):
     ''' convert symbols like I(this is in italics) to valid HTML '''
 
@@ -41,11 +52,18 @@ def html_ify(text):
     text, _counts['bold'] = _BOLD.subn(r"<b>\1</b>", text)
     text, _counts['module'] = _MODULE.subn(
         r"<a href='../../\1/\2/\3_module.html' class='module'>\1.\2.\3</a>", text)
+    text, _counts['plugin'] = _PLUGIN.subn(
+        r"<a href='../../\1/\2/\3_\4.html' class='module plugin-\4'>\1.\2.\3</span>", text)
     text, _counts['url'] = _URL.subn(r"<a href='\1'>\1</a>", text)
     text, _counts['ref'] = _REF.subn(r"<span class='module'>\1</span>", text)
     text, _counts['link'] = _LINK.subn(r"<a href='\2'>\1</a>", text)
     text, _counts['const'] = _CONST.subn(
         r"<code class='docutils literal notranslate'>\1</code>", text)
+    text, _counts['option-name'] = _SEM_OPTION_NAME.subn(_option_name_html, text)
+    text, _counts['option-value'] = _SEM_OPTION_VALUE.subn(
+        r"<code class='docutils literal notranslate'>\1</code>", text)
+    text, _counts['environment-var'] = _SEM_ENV_VARIABLE.subn(
+        r"<code class='docutils literal notranslate'>\1</code>", text)
     text, _counts['ruler'] = _RULER.subn(r"<hr/>", text)
 
     text = text.strip()
@@ -80,6 +98,15 @@ def do_max(seq):
 # https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#character-level-inline-markup-1
 # for further information.
 
+def _option_name_rst(matcher):
+    parts = matcher.group(1).split('=', 1)
+    start = f"\\ :strong:`{rst_escape(parts[0], escape_ending_whitespace=True)}`\\ "
+    if len(parts) == 1:
+        return start
+    end = f"\\ :literal:`{rst_escape(parts[1], escape_ending_whitespace=True)}`\\ "
+    return f'{start}={end}'
+
+
 def _rst_ify_italic(m: 're.Match') -> str:
     return f"\\ :emphasis:`{rst_escape(m.group(1), escape_ending_whitespace=True)}`\\ "
 
@@ -130,6 +157,9 @@ def rst_ify(text):
     text, _counts['url'] = _URL.subn(_rst_ify_url, text)
     text, _counts['ref'] = _REF.subn(_rst_ify_ref, text)
     text, _counts['const'] = _CONST.subn(_rst_ify_const, text)
+    text, _counts['option-name'] = _SEM_OPTION_NAME.subn(_option_name_rst, text)
+    text, _counts['option-value'] = _SEM_OPTION_VALUE.subn(_rst_ify_const, text)
+    text, _counts['environment-var'] = _SEM_ENV_VARIABLE.subn(_rst_ify_const, text)
     text, _counts['ruler'] = _RULER.subn('\n\n.. raw:: html\n\n  <hr>\n\n', text)
 
     flog.fields(counts=_counts).info('Number of macros converted to rst equivalents')