Add lua_ls_max_version

Author: taminomara

CHANGELOG.md

@@ -10,6 +10,9 @@
   They also allow overriding object's signature, which may be useful when
   automatically generated signature is too long.
 
+- Added `lua_ls_max_version` config option to safeguard against incompatible changes
+  to documentation export format.
+
 ## [3.4.0]
 
 - **Potential breaking change:** use `confdir` instead of `srcdir` as base path

docs/source/settings.rst

@@ -36,7 +36,21 @@ Settings
 .. py:data:: lua_ls_min_version
    :type: str
 
-   Controls the minimal version of the used lua analyzer.
+   Controls the minimum version of the used lua analyzer.
+
+   Analyzer version should be greater than or equal to this version.
+
+   For LuaLs, default value is ``3.0.0``, for EmmyLua it's ``0.11.0``.
+
+.. py:data:: lua_ls_max_version
+   :type: str | None
+
+   Controls the maximum version of the used lua analyzer.
+
+   Analyzer version should be strictly less than this version.
+
+   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_default_options
    :type: dict[str, str]

sphinx_lua_ls/__init__.py

@@ -64,12 +64,19 @@ def run_lua_ls(app: sphinx.application.Sphinx):
             min_version = "3.0.0"
         else:
             min_version = "0.11.0"
+    max_version = domain.config.max_version
+    if max_version == "__auto__":
+        if domain.config.backend == "luals":
+            max_version = "4.0.0"
+        else:
+            max_version = "2.0.0"
 
     cwd = pathlib.Path.cwd()
     try:
         runner = sphinx_lua_ls.lua_ls.resolve(
             backend=domain.config.backend,
             min_version=min_version,
+            max_version=max_version,
             cwd=root_dir,
             reporter=sphinx_lua_ls.lua_ls.SphinxProgressReporter(app.verbosity),
             install=domain.config.auto_install,
@@ -187,6 +194,7 @@ def setup(app: sphinx.application.Sphinx):
     app.add_config_value("lua_ls_auto_install", True, rebuild="")
     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_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

@@ -24,6 +24,7 @@ class LuaDomainConfig:
     auto_install: bool = True
     auto_install_location: pathlib.Path | None = None
     min_version: str | None = None
+    max_version: 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)
@@ -214,6 +215,10 @@ def set_options(app: sphinx.application.Sphinx):
         domain_config.min_version = _version(
             "lua_ls_min_version", config["lua_ls_min_version"]
         )
+    if config["lua_ls_max_version"] is not None:
+        domain_config.max_version = _version(
+            "lua_ls_max_version", config["lua_ls_max_version"]
+        )
 
     if config["lua_ls_lua_version"]:
         domain_config.lua_version = _str_choices(