lsp: Implement completion argument suggestions for MyST

Author: alcarney

lib/esbonio/esbonio/server/features/directives/completion.py

@@ -172,12 +172,12 @@ def render_rst_directive_with_insert_text(
 
 
 @directive_argument_renderer(language="rst", insert_behavior="replace")
-def render_directive_agument_with_text_edit(
+def render_rst_argument_with_text_edit(
     context: server.CompletionContext, item: types.CompletionItem
 ) -> types.CompletionItem | None:
     """Render a ``CompletionItem`` using ``textEdit``.
 
-    This implements the ``replace`` insert behavior for role targets.
+    This implements the ``replace`` insert behavior for rst directive arguments.
 
     Parameters
     ----------
@@ -296,6 +296,30 @@ def render_myst_directive_with_text_edit(
     return item
 
 
+@directive_argument_renderer(language="markdown", insert_behavior="replace")
+def render_myst_argument_with_text_edit(
+    context: server.CompletionContext, item: types.CompletionItem
+) -> types.CompletionItem | None:
+    """Render a ``CompletionItem`` using ``textEdit``.
+
+    This implements the ``replace`` insert behavior for MyST directive arguments.
+
+    Parameters
+    ----------
+    context
+       The context in which the completion is being generated.
+
+    item
+       The ``CompletionItem`` representing the directive argument.
+
+    Returns
+    -------
+    Optional[types.CompletionItem]
+       The rendered completion item, or ``None`` if the item should be skipped
+    """
+    return item
+
+
 @directive_renderer(language="markdown", insert_behavior="insert")
 def render_myst_directive_with_insert_text(
     context: server.CompletionContext,

lib/esbonio/esbonio/server/features/myst/directives.py

@@ -21,7 +21,7 @@ def __init__(self, directives: DirectiveFeature, *args, **kwargs):
     completion_trigger = server.CompletionTrigger(
         patterns=[MYST_DIRECTIVE],
         languages={"markdown"},
-        characters={".", "`", "/"},
+        characters={".", "`", "/", "{"},
     )
 
     def initialized(self, params: types.InitializedParams):
@@ -49,24 +49,44 @@ async def completion(
         if "directive" not in groups:
             return await self.complete_options(context)
 
-        # Don't offer completions for targets
-        if (groups["name"] or "").startswith("_"):
-            return None
-
         # Are we completing the directive's argument?
         directive_end = context.match.span()[0] + len(groups["directive"])
         complete_directive = groups["directive"].endswith("}")
 
+        directive_name = groups["name"]
         if complete_directive and directive_end < context.position.character:
-            return await self.complete_arguments(context)
+            return await self.complete_arguments(context, directive_name)
+
+        # Provide argument suggestions for `code-block` if the user is creating a regular code block.
+        if "{" not in groups["directive"]:
+            return await self.complete_arguments(context, "code-block")
 
         return await self.complete_directives(context)
 
     async def complete_options(self, context: server.CompletionContext):
         return None
 
-    async def complete_arguments(self, context: server.CompletionContext):
-        return None
+    async def complete_arguments(
+        self,
+        context: server.CompletionContext,
+        directive_name: str,
+    ) -> list[types.CompletionItem] | None:
+        """Return completion suggestions for the current directive's argument."""
+
+        render_func = completion.get_directive_argument_renderer(
+            context.language, self._insert_behavior
+        )
+        if render_func is None:
+            return None
+
+        items = []
+        suggestions = await self.directives.suggest_arguments(context, directive_name)
+
+        for argument in suggestions:
+            if (item := render_func(context, argument)) is not None:
+                items.append(item)
+
+        return items if len(items) > 0 else None
 
     async def complete_directives(
         self, context: server.CompletionContext

lib/esbonio/esbonio/sphinx_agent/types/directives.py

@@ -21,7 +21,6 @@
     (\s*)                             # directives can be indented
     (?P<directive>
       ```(`*)?                        # directives start with at least 3 ` chars
-      (?!\w)                          # -- regular code blocks are not directives
       [{]?                            # followed by an opening brace
       (?P<name>[^}]+)?                # directives have a name
       [}]?                            # directives are closed with a closing brace

lib/esbonio/tests/workspaces/demo/myst/directives.md

@@ -9,3 +9,33 @@ The most obvious feature is the completion suggestions, try inserting a `{note}`
 % Add your note here...
 
 Notice how VSCode automatically presented you with a list of all the directives you can use in this Sphinx project?
+
+### Arguments
+
+While directive names Just Work{sup}`TM`, Esbonio is only able to offer suggestions for specific argument types.
+By default Esbonio can provide suggestions for
+
+**Filepaths**
+
+Completing filepath arguments is supported for the following directives
+
+- [`figure`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)
+- [`image`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image)
+- [`include`](https://docutils.sourceforge.io/docs/ref/rst/directives.html#image)
+- {external+sphinx:rst:dir}`literalinclude`
+
+% Try using the `literalinclude` directive to insert the contents of this project's conf.py here...
+
+
+**Pygments Lexers**
+
+Sphinx uses the [pygments](https://pygments.org/) library for its syntax highlighting, Esbonio will offer the names of available lexers as suggestions for the following directives.
+
+- {external+sphinx:rst:dir}`code`
+- {external+sphinx:rst:dir}`code-block`
+- {external+sphinx:rst:dir}`highlight`
+- {external+sphinx:rst:dir}`sourcecode`
+
+Of course MyST allows you to use standard Markdown code blocks as well, Esbonio will also offer suggestions in this context.
+
+% Try inserting a code block on the next line...