From cc561e961aafd3ae70d24a7c89c586aa67975682 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois?= <francois@beafrancois.fr>
Date: Sat, 30 May 2026 15:43:44 +0200
Subject: [PATCH] manual: document the language server + parameter validation
 (0.2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

modes.rst: new 'Language server (editor support)' section — testium lsp /
testium schema, the testium_assist client, the [lsp] extra. tum_syntax.rst:
a note on parameter validation (unknown-key warning, missing-required error).
Builds clean (sphinx html, no RST errors).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 doc/manual/sphinx/source/modes.rst      | 44 +++++++++++++++++++++++++
 doc/manual/sphinx/source/tum_syntax.rst |  9 +++++
 2 files changed, 53 insertions(+)

diff --git a/doc/manual/sphinx/source/modes.rst b/doc/manual/sphinx/source/modes.rst
index c95d6d1..b21c82c 100644
--- a/doc/manual/sphinx/source/modes.rst
+++ b/doc/manual/sphinx/source/modes.rst
@@ -23,3 +23,47 @@ graphical interface.
     :caption: call a test in batch mode
 
     testium -b test/my_test/main.tum
+
+.. _sec_language_server:
+
+Language server (editor support)
+--------------------------------
+
+*testium* ships a `Language Server Protocol
+<https://microsoft.github.io/language-server-protocol/>`_ server so that
+``.tum`` files get editor assistance — completion of test item types, hover
+documentation of their parameters, and an outline view — in any LSP-capable
+editor.
+
+The server speaks LSP over standard input/output and is started with:
+
+.. code-block:: text
+    :caption: start the language server
+
+    testium lsp
+
+It is not meant to be launched directly by the user: an editor's LSP client
+spawns it and drives the exchange. A VSCode / VSCodium client extension,
+*testium_assist*, is provided for that purpose; any other LSP client (Neovim,
+Emacs ``lsp-mode``, …) can be pointed at ``testium lsp`` as well.
+
+The information the server exposes is the test item schema, which can also be
+dumped as JSON for inspection or tooling:
+
+.. code-block:: text
+    :caption: dump the item / parameter schema
+
+    testium schema
+
+Because the schema is built from *testium* itself, every new item type or
+parameter becomes available in the editor on the next *testium* upgrade, with
+no change to the client.
+
+The language server is included in the pre-built binary, Flatpak and AppImage
+releases. For a source or wheel installation, pull the optional ``lsp``
+dependencies:
+
+.. code-block:: text
+    :caption: enable the language server for a wheel / source install
+
+    pip install 'testium[lsp]'
diff --git a/doc/manual/sphinx/source/tum_syntax.rst b/doc/manual/sphinx/source/tum_syntax.rst
index 0997d2b..e3d10b5 100644
--- a/doc/manual/sphinx/source/tum_syntax.rst
+++ b/doc/manual/sphinx/source/tum_syntax.rst
@@ -232,6 +232,15 @@ list of the main test item (and eventually of the loop test item).
 TUM file ``main`` item is itself a variant of test items with a name and an
 step list attributes.
 
+.. note::
+
+   Each test item declares the parameters it accepts. When a ``.tum`` file
+   uses a key the item does not know, *testium* emits a warning listing the
+   accepted parameter names (catching typos such as ``param_filee`` for
+   ``param_file``); a missing **required** parameter aborts loading with an
+   error pointing at the source ``.tum`` file. Valid existing tests are
+   unaffected.
+
 
 
 .. toctree::