Add lua_ls_skip_versions

Author: taminomara

.github/workflows/ci.yaml

@@ -26,11 +26,11 @@ jobs:
       - name: Install dependencies
         run: python -m pip install '.'
       - name: Download LuaLs for Linux
-        run: python sphinx_lua_ls/lua_ls.py linux x86_64 --runtime luals ~/lua_ls_release/ubuntu-latest
+        run: python sphinx_lua_ls/lua_ls.py linux x86_64 --runtime luals --skip 3.16.0 ~/lua_ls_release/ubuntu-latest
       - name: Download LuaLs for Windows
-        run: python sphinx_lua_ls/lua_ls.py win32 amd64 --runtime luals ~/lua_ls_release/windows-latest
+        run: python sphinx_lua_ls/lua_ls.py win32 amd64 --runtime luals --skip 3.16.0 ~/lua_ls_release/windows-latest
       - name: Download LuaLs for MacOs
-        run: python sphinx_lua_ls/lua_ls.py darwin arm --runtime luals ~/lua_ls_release/macos-latest
+        run: python sphinx_lua_ls/lua_ls.py darwin arm --runtime luals --skip 3.16.0 ~/lua_ls_release/macos-latest
       - name: Download EmmyLua for Linux
         run: python sphinx_lua_ls/lua_ls.py linux x86_64 --runtime emmylua ~/lua_ls_release/ubuntu-latest
       - name: Download EmmyLua for Windows

CHANGELOG.md

@@ -2,7 +2,10 @@
 
 ## [Unreleased]
 
-- Support Sphinx 9.
+- Added support Sphinx 9.
+
+- Added ``lua_ls_skip_versions`` config option to selectively avoid certain
+  language server releases.
 
 ## [3.7.0-post1] - 2025-11-14
 

CONTRIBUTING.md

@@ -10,8 +10,12 @@
 
    ```shell
    pip install -e . --group dev
+   pip install -U sphinx
    ```
 
+   > *Note:* our tests run with Sphinx 9, but some dependencies are not yet updated
+   > for it; that's why you have to update Sphinx after installing it.
+
 4. Install pre-commit hooks:
 
    ```shell

docs/source/settings.rst

@@ -52,6 +52,17 @@ Settings
    For LuaLs, default value is ``4.0.0``, for EmmyLua it's ``2.0.0``.
    Use ``None`` to allow any version.
 
+.. py:data:: lua_ls_skip_versions
+   :type: list[str] | None
+
+   List of lua analyzer versions that shouldn't be used.
+
+   For example, if ``lua_ls_skip_versions = ["3.16"]``, language server release
+   ``3.16`` (including all ``3.16.x`` releases) will not be used.
+
+   This setting can be used to avoid broken releases without limiting max version
+   of the lua analyzer.
+
 .. py:data:: lua_ls_default_options
    :type: dict[str, str]
 
@@ -99,12 +110,12 @@ Settings
    and :rst:dir:`lua:autoobject:class-signature` options.
 
 .. py:data:: lua_ls_class_default_force_non_colon
-   :type:
+   :type: bool
 
    If ``True``, Sphinx-LuaLs will remove ``self`` from class constructor's signature.
 
 .. py:data:: lua_ls_class_default_force_return_self
-   :type:
+   :type: bool
 
    If ``True``, Sphinx-LuaLs will replace class constructor's return type with ``self``.
 

sphinx_lua_ls/__init__.py

@@ -70,13 +70,15 @@ def run_lua_ls(app: sphinx.application.Sphinx):
             max_version = "4.0.0"
         else:
             max_version = "2.0.0"
+    skip_versions = domain.config.skip_versions
 
     cwd = pathlib.Path.cwd()
     try:
         runner = sphinx_lua_ls.lua_ls.resolve(
             backend=domain.config.backend,
             min_version=min_version,
             max_version=max_version,
+            skip_versions=skip_versions or [],
             cwd=root_dir,
             reporter=sphinx_lua_ls.lua_ls.SphinxProgressReporter(app.verbosity),
             install=domain.config.auto_install,
@@ -195,6 +197,7 @@ def setup(app: sphinx.application.Sphinx):
     app.add_config_value("lua_ls_auto_install_location", None, rebuild="")
     app.add_config_value("lua_ls_min_version", None, rebuild="env")
     app.add_config_value("lua_ls_max_version", "__auto__", rebuild="env")
+    app.add_config_value("lua_ls_skip_versions", None, rebuild="env")
     app.add_config_value("lua_ls_lua_version", None, rebuild="html")
     app.add_config_value("lua_ls_default_options", None, rebuild="env")
     app.add_config_value("lua_ls_apidoc_roots", None, rebuild="")

sphinx_lua_ls/config.py

@@ -14,6 +14,7 @@
 _logger = logging.getLogger("sphinx_lua_ls")
 
 T = _t.TypeVar("T")
+A = _t.ParamSpec("A")
 
 
 @dataclass
@@ -25,6 +26,7 @@ class LuaDomainConfig:
     auto_install_location: pathlib.Path | None = None
     min_version: str | None = None
     max_version: str | None = None
+    skip_versions: list[str] | None = None
     lua_version: str | None = None
     default_options: dict[str, _t.Any] = dataclasses.field(default_factory=dict)
     apidoc_default_options: dict[str, _t.Any] = dataclasses.field(default_factory=dict)
@@ -73,11 +75,17 @@ def _path(name: str, value, root: str | pathlib.Path) -> pathlib.Path:
         raise ConfigError(f"incorrect lua_ls_project_root: {e}") from None
 
 
-def _paths(name: str, value, root: str | pathlib.Path) -> list[pathlib.Path]:
+def _list(
+    name: str,
+    value,
+    checker: _t.Callable[_t.Concatenate[str, object, A], T],
+    *args: A.args,
+    **kwargs: A.kwargs,
+) -> list[T]:
     if value is None:
         value = []
     _type(name, value, list)
-    return [_path(f"{name}[{i}]", v, root) for i, v in enumerate(value)]
+    return [checker(f"{name}[{i}]", v, *args, **kwargs) for i, v in enumerate(value)]
 
 
 def _options(name: str, value) -> dict[str, _t.Any]:
@@ -193,9 +201,10 @@ def set_options(app: sphinx.application.Sphinx):
         )
 
     if config["lua_ls_project_directories"] is not None:
-        domain_config.project_directories = _paths(
+        domain_config.project_directories = _list(
             "lua_ls_project_directories",
             config["lua_ls_project_directories"],
+            _path,
             domain_config.project_root,
         )
 
@@ -221,6 +230,10 @@ def set_options(app: sphinx.application.Sphinx):
             if config["lua_ls_max_version"] != "__auto__"
             else "__auto__"
         )
+    if config["lua_ls_skip_versions"] is not None:
+        domain_config.skip_versions = _list(
+            "lua_ls_skip_versions", config["lua_ls_skip_versions"], _version
+        )
 
     if config["lua_ls_lua_version"]:
         domain_config.lua_version = _str_choices(