lsp: Implement completion suggestions for .. code-block::

and `.. highlight::` and `.. source-code::`

Author: alcarney

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

@@ -10,10 +10,42 @@
 from esbonio.sphinx_agent import types
 
 if typing.TYPE_CHECKING:
+    import logging
+    from typing import Any
+
+    import cattrs
+
+    from esbonio.server import EsbonioLanguageServer
     from esbonio.server import Uri
     from esbonio.server.features.project_manager import Project
 
 
+class ValuesProvider(directives.DirectiveArgumentProvider):
+    """Simple completions provider that supports a static list of values."""
+
+    def __init__(self, converter: cattrs.Converter, logger: logging.Logger):
+        self.converter = converter
+        self.logger = logger
+
+    def suggest_arguments(  # type: ignore[override]
+        self, context: server.CompletionContext, *, values: list[str | dict[str, Any]]
+    ) -> list[lsp.CompletionItem]:
+        """Given a completion context, suggest directive arguments that may be used."""
+        result: list[lsp.CompletionItem] = []
+
+        for value in values:
+            if isinstance(value, str):
+                result.append(lsp.CompletionItem(label=value))
+                continue
+
+            try:
+                result.append(self.converter.structure(value, lsp.CompletionItem))
+            except Exception:
+                self.logger.exception("Unable to create CompletionItem")
+
+        return result
+
+
 class SphinxDirectives(directives.DirectiveProvider):
     """Support for directives in a sphinx project."""
 
@@ -96,8 +128,15 @@ async def suggest_directives(
 
 
 def esbonio_setup(
+    esbonio: EsbonioLanguageServer,
     project_manager: ProjectManager,
     directive_feature: directives.DirectiveFeature,
 ):
     provider = SphinxDirectives(project_manager)
+
+    values_provider = ValuesProvider(
+        esbonio.converter, esbonio.logger.getChild("ValuesProvider")
+    )
+
     directive_feature.add_directive_provider(provider)
+    directive_feature.add_directive_argument_provider("values", values_provider)

lib/esbonio/esbonio/sphinx_agent/handlers/directives.py

@@ -6,6 +6,7 @@
 
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst import directives as docutils_directives
+from pygments.lexers import get_all_lexers
 
 from .. import types
 from ..app import Database
@@ -100,6 +101,8 @@ def index_directives(app: Sphinx):
 
         directives[name] = types.Directive(name, get_impl_name(directive))
 
+    _add_providers(directives)
+
     app.esbonio.db.ensure_table(DIRECTIVES_TABLE)
     app.esbonio.db.clear_table(DIRECTIVES_TABLE)
     app.esbonio.db.insert_values(
@@ -109,3 +112,36 @@ def index_directives(app: Sphinx):
 
 def setup(app: Sphinx):
     app.connect("builder-inited", index_directives, priority=999)
+
+
+def _add_providers(directives: dict[str, types.Directive]):
+    """Add provider definitions to built in directive types we know about."""
+
+    lexers_provider = _get_lexers_provider()
+
+    for name in ["code-block", "sourcecode", "highlight"]:
+        if (directive := directives.get(name)) is not None:
+            directive.argument_providers = [lexers_provider]
+
+
+def _get_lexers_provider() -> types.Directive.ArgumentProvider:
+    """Get the argument provider instance that returns the names of pygments lexers."""
+
+    langs = []
+    for name, labels, files, mimes in get_all_lexers():
+        filenames = ", ".join(f"`{f}`" for f in files)
+        mimetypes = ", ".join(f"`{m}`" for m in mimes)
+
+        for label in labels:
+            langs.append(
+                {
+                    "label": label,
+                    "kind": 21,  # Constant
+                    "documentation": {
+                        "kind": "markdown",
+                        "value": f"### {name}\nFilenames: {filenames}\n\nMIME Types: {mimetypes}",
+                    },
+                }
+            )
+
+    return types.Directive.ArgumentProvider("values", {"values": langs})