Support semantic markup for roles

changelogs/fragments/9-semantic-markup-roles.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - "Add support for semantic markup in roles (https://github.com/ansible-community/antsibull-docs-parser/pull/9)."
+breaking_changes:
+  - "Modify ``LinkProvider.plugin_option_like_link`` signature to include optional string argument ``entrypoint`` after ``plugin`` (https://github.com/ansible-community/antsibull-docs-parser/pull/9)."

src/antsibull_docs_parser/dom.py

@@ -94,6 +94,7 @@ class CodePart(NamedTuple):
 
 class OptionNamePart(NamedTuple):
     plugin: t.Optional[PluginIdentifier]
+    entrypoint: t.Optional[str]  # present iff plugin.type == 'role'
     link: t.List[str]
     name: str
     value: t.Optional[str]
@@ -112,6 +113,7 @@ class EnvVariablePart(NamedTuple):
 
 class ReturnValuePart(NamedTuple):
     plugin: t.Optional[PluginIdentifier]
+    entrypoint: t.Optional[str]  # present iff plugin.type == 'role'
     link: t.List[str]
     name: str
     value: t.Optional[str]

src/antsibull_docs_parser/format.py

@@ -28,6 +28,7 @@ def plugin_link(  # pylint:disable=no-self-use
     def plugin_option_like_link(  # pylint:disable=no-self-use
         self,
         plugin: dom.PluginIdentifier,  # pylint:disable=unused-argument
+        entrypoint: t.Optional[str],  # pylint:disable=unused-argument
         # pylint:disable-next=unused-argument
         what: "t.Union[t.Literal['option'], t.Literal['retval']]",
         # pylint:disable-next=unused-argument
@@ -174,7 +175,11 @@ def process_option_name(self, part: dom.OptionNamePart) -> None:
         url = None
         if part.plugin:
             url = self.link_provider.plugin_option_like_link(
-                part.plugin, "option", part.link, part.plugin == self.current_plugin
+                part.plugin,
+                part.entrypoint,
+                "option",
+                part.link,
+                part.plugin == self.current_plugin,
             )
         self.destination.append(self.formatter.format_option_name(part, url))
 
@@ -189,7 +194,11 @@ def process_return_value(self, part: dom.ReturnValuePart) -> None:
         url = None
         if part.plugin:
             url = self.link_provider.plugin_option_like_link(
-                part.plugin, "retval", part.link, part.plugin == self.current_plugin
+                part.plugin,
+                part.entrypoint,
+                "retval",
+                part.link,
+                part.plugin == self.current_plugin,
             )
         self.destination.append(self.formatter.format_return_value(part, url))
 

src/antsibull_docs_parser/parser.py

@@ -35,6 +35,7 @@ def _is_plugin_type(text: str) -> bool:
 
 class Context(t.NamedTuple):
     current_plugin: t.Optional[dom.PluginIdentifier] = None
+    role_entrypoint: t.Optional[str] = None
 
 
 class CommandParser(abc.ABC):
@@ -146,10 +147,13 @@ def parse(self, parameters: t.List[str], context: Context) -> dom.AnyPart:
 def _parse_option_like(
     text: str,
     context: Context,
-) -> t.Tuple[t.Optional[dom.PluginIdentifier], t.List[str], str, t.Optional[str]]:
+) -> t.Tuple[
+    t.Optional[dom.PluginIdentifier], t.Optional[str], t.List[str], str, t.Optional[str]
+]:
     value = None
     if "=" in text:
         text, value = text.split("=", 1)
+    entrypoint: t.Optional[str] = None
     m = _FQCN_TYPE_PREFIX_RE.match(text)
     if m:
         plugin_fqcn = m.group(1)
@@ -165,10 +169,19 @@ def _parse_option_like(
         text = text[len(_IGNORE_MARKER) :]
     else:
         plugin_identifier = context.current_plugin
+        entrypoint = context.role_entrypoint
+    if plugin_identifier is not None and plugin_identifier.type == "role":
+        idx = text.find(":")
+        if idx >= 0:
+            entrypoint = text[:idx]
+            text = text[idx + 1 :]
+        if entrypoint is None:
+            raise ValueError("Role reference is missing entrypoint")
     if ":" in text or "#" in text:
         raise ValueError(f'Invalid option/return value name "{text}"')
     return (
         plugin_identifier,
+        entrypoint,
         _ARRAY_STUB_RE.sub("", text).split("."),
         text,
         value,
@@ -212,17 +225,25 @@ def __init__(self):
         super().__init__("O", 1, escaped_arguments=True)
 
     def parse(self, parameters: t.List[str], context: Context) -> dom.AnyPart:
-        plugin, link, name, value = _parse_option_like(parameters[0], context)
-        return dom.OptionNamePart(plugin=plugin, link=link, name=name, value=value)
+        plugin, entrypoint, link, name, value = _parse_option_like(
+            parameters[0], context
+        )
+        return dom.OptionNamePart(
+            plugin=plugin, entrypoint=entrypoint, link=link, name=name, value=value
+        )
 
 
 class _ReturnValue(CommandParserEx):
     def __init__(self):
         super().__init__("RV", 1, escaped_arguments=True)
 
     def parse(self, parameters: t.List[str], context: Context) -> dom.AnyPart:
-        plugin, link, name, value = _parse_option_like(parameters[0], context)
-        return dom.ReturnValuePart(plugin=plugin, link=link, name=name, value=value)
+        plugin, entrypoint, link, name, value = _parse_option_like(
+            parameters[0], context
+        )
+        return dom.ReturnValuePart(
+            plugin=plugin, entrypoint=entrypoint, link=link, name=name, value=value
+        )
 
 
 _COMMANDS = [

src/antsibull_docs_parser/rst.py

@@ -44,6 +44,10 @@ def _format_option_like(
             result.append("#")
             result.append(plugin.type)
             result.append(":")
+        entrypoint = part.entrypoint
+        if entrypoint is not None:
+            result.append(entrypoint)
+            result.append(":")
         result.append(part.name)
         value = part.value
         if value is not None: