sphinx-lua-ls 3.9.0__tar.gz → 3.10.0__tar.gz

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/.github/workflows/ci.yaml

@@ -126,13 +126,12 @@ jobs:
           ref="${{ github.ref }}";
           version=${ref#refs/tags/v};
           link="https://pypi.org/p/sphinx-lua-ls/${version}";
-          echo "version=${version}" >> $GITHUB_OUTPUT
           echo "link=${link}" >> $GITHUB_OUTPUT
       - name: Parse Changelog
         id: changelog
-        uses: mindsers/changelog-reader-action@v2
+        uses: taminomara/cl-keeper@v0
         with:
-          version: ${{ steps.metadata.outputs.version }}
+          version: ${{ github.ref }}
       - name: Set up python 3.12
         uses: actions/setup-python@v4
         with:
@@ -150,11 +149,11 @@ jobs:
       - name: Create GitHub release
         uses: softprops/action-gh-release@v2
         with:
-          prerelease: ${{ steps.changelog.outputs.status == 'prereleased' }}
-          draft: ${{ steps.changelog.outputs.status == 'unreleased' }}
+          prerelease: ${{ fromJSON(steps.changelog.outputs.is-pre-release) }}
+          draft: ${{ fromJSON(steps.changelog.outputs.is-unreleased) }}
           body: |
             ## Changelog
 
-            ${{ steps.changelog.outputs.changes }}
+            ${{ steps.changelog.outputs.text }}
 
             [See release on PyPi](${{ steps.metadata.outputs.link }})

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/.pre-commit-config.yaml

@@ -13,6 +13,20 @@ repos:
         entry: isort --filter-files
         types_or: [python, pyi]
         require_serial: true
+      - id: clk
+        name: changelog keeper
+        language: system
+        entry: clk pre-commit-check
+        require_serial: true
+        types_or: [toml, yaml, markdown]
+      - id: clk-tags
+        name: changelog keeper (check tags)
+        language: system
+        entry: clk pre-commit-check-tag
+        always_run: true
+        pass_filenames: false
+        require_serial: true
+        stages: [pre-push]
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [3.10.0] - 2026-01-29
+
+- Added option to disable running lua-ls (`lua_ls_backend = "disable"`) for cases when
+  only manual documentation is required ([#47] by [@pieterlexis]).
+
 ## [3.9.0] - 2026-01-23
 
 - Fixed LaTeX build and improved rendering of multiline signatures in LaTeX ([#46]).
@@ -251,10 +256,11 @@ Initial release.
 
 ## [0.0.1] - 2025-03-09
 
-[#46]:https://github.com/sphinx-contrib/lua-ls/issues/46
 [#18]: https://github.com/sphinx-contrib/lua-ls/pull/18
 [#19]: https://github.com/sphinx-contrib/lua-ls/pull/19
 [#3]: https://github.com/sphinx-contrib/lua-ls/issues/3
+[#46]: https://github.com/sphinx-contrib/lua-ls/issues/46
+[#47]: https://github.com/sphinx-contrib/lua-ls/pull/47
 [0.0.1]: https://github.com/sphinx-contrib/lua-ls/releases/tag/v0.0.1
 [0.0.2]: https://github.com/sphinx-contrib/lua-ls/compare/v0.0.1...v0.0.2
 [0.0.3]: https://github.com/sphinx-contrib/lua-ls/compare/v0.0.2...v0.0.3
@@ -265,6 +271,7 @@ Initial release.
 [2.0.1]: https://github.com/sphinx-contrib/lua-ls/compare/v2.0.0...v2.0.1
 [3.0.0]: https://github.com/sphinx-contrib/lua-ls/compare/v2.0.1...v3.0.0
 [3.1.0]: https://github.com/sphinx-contrib/lua-ls/compare/v3.0.0...v3.1.0
+[3.10.0]: https://github.com/sphinx-contrib/lua-ls/compare/v3.9.0...v3.10.0
 [3.2.0]: https://github.com/sphinx-contrib/lua-ls/compare/v3.1.0...v3.2.0
 [3.3.0]: https://github.com/sphinx-contrib/lua-ls/compare/v3.2.0...v3.3.0
 [3.4.0]: https://github.com/sphinx-contrib/lua-ls/compare/v3.3.0...v3.4.0
@@ -277,6 +284,7 @@ Initial release.
 [3.8.1]: https://github.com/sphinx-contrib/lua-ls/compare/v3.8.0...v3.8.1
 [3.9.0]: https://github.com/sphinx-contrib/lua-ls/compare/v3.8.1...v3.9.0
 [@bkoropoff]: https://github.com/bkoropoff
+[@pieterlexis]: https://github.com/pieterlexis
 [emmylua]: https://github.com/EmmyLuaLs/emmylua-analyzer-rust/
 [luals#3301]: https://github.com/LuaLS/lua-language-server/issues/3301
-[unreleased]: https://github.com/sphinx-contrib/lua-ls/compare/v3.9.0...HEAD
+[unreleased]: https://github.com/sphinx-contrib/lua-ls/compare/v3.10.0...HEAD

{sphinx_lua_ls-3.9.0/sphinx_lua_ls.egg-info → sphinx_lua_ls-3.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-lua-ls
-Version: 3.9.0
+Version: 3.10.0
 Summary: Automatic documentation generation via EmmyLua/LuaLs
 Author-email: Tamika Nomara <taminomara@gmail.com>
 License-Expression: MIT

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/docs/source/settings.rst

@@ -18,7 +18,9 @@ Settings
 .. py:data:: lua_ls_backend
    :type: str
 
-   Controls which lua analyzer is used. Can be either ``"emmylua"`` or ``"luals"``.
+   Controls which lua analyzer is used. Can be either ``"emmylua"``, ``"luals"``, or ``"disable"``.
+   When set to ``"disable"``, no Lua files are analyzed, all language server related settings
+   are ignored, and :doc:`autodoc` does not work.
 
 .. py:data:: lua_ls_auto_install
    :type: bool

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-lua-ls"
-authors = [{name = "Tamika Nomara", email = "taminomara@gmail.com"}]
+authors = [{ name = "Tamika Nomara", email = "taminomara@gmail.com" }]
 description = "Automatic documentation generation via EmmyLua/LuaLs"
 dynamic = ["version"]
 readme = "README.md"
@@ -21,23 +21,20 @@ classifiers = [
     "Topic :: Documentation :: Sphinx",
     "Typing :: Typed",
 ]
-dependencies = [
-    "sphinx>=8.0,<10.0",
-    "PyGithub>=1.59,<3.0",
-    "requests~=2.31",
-]
+dependencies = ["sphinx>=8.0,<10.0", "PyGithub>=1.59,<3.0", "requests~=2.31"]
 
 [dependency-groups]
 dev = [
     "pytest-cov==7.0.0",
-    {include-group = "test"},
-    {include-group = "lint"},
-    {include-group = "doc"},
+    { include-group = "test" },
+    { include-group = "lint" },
+    { include-group = "doc" },
 ]
 lint = [
-    "black==25.12.0",
+    "black==26.1.0",
     "isort==7.0.0",
-    "pre-commit==4.5.0",
+    "pre-commit==4.5.1",
+    "cl-keeper==0.0.0-b6",
 ]
 test = [
     "pyright==1.1.408",
@@ -45,13 +42,13 @@ test = [
     "sybil==9.3.0",
     "pytest-regressions==2.9.1",
     "beautifulsoup4==4.14.3",
-    "myst-parser==5.0.0"
+    "myst-parser==5.0.0",
 ]
 doc = [
     "sybil==9.3.0",
     "furo==2025.12.19",
     "sphinx_design==0.7.0",
-    "myst-parser==5.0.0"
+    "myst-parser==5.0.0",
 ]
 
 [project.urls]

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/sphinx_lua_ls/__init__.py

@@ -33,6 +33,9 @@ logger = logging.getLogger("sphinx_lua_ls")
 def run_lua_ls(app: sphinx.application.Sphinx):
     domain: sphinx_lua_ls.domain.LuaDomain = app.env.get_domain("lua")  # type: ignore
 
+    if domain.config.backend == "disable":
+        return
+
     root_dir = domain.config.project_root
     project_directories = domain.config.project_directories
     if project_directories is None:
@@ -130,6 +133,12 @@ def run_apidoc(
     app: sphinx.application.Sphinx,
 ):
     domain = _t.cast(sphinx_lua_ls.domain.LuaDomain, app.env.get_domain("lua"))
+    if domain.config.backend == "disable":
+        logger.warning(
+            "apidoc requested, but the language server backend is disabled",
+            type="lua-ls",
+        )
+        return
     cwd = pathlib.Path.cwd()
     for name, params in domain.config.apidoc_roots.items():
         try:

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/sphinx_lua_ls/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.9.0'
-__version_tuple__ = version_tuple = (3, 9, 0)
+__version__ = version = '3.10.0'
+__version_tuple__ = version_tuple = (3, 10, 0)
 
-__commit_id__ = commit_id = 'gfa7ddc7ee'
+__commit_id__ = commit_id = 'g73d8efc53'

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/sphinx_lua_ls/apidoc.py

@@ -22,8 +22,7 @@ _ENV.filters["h2"] = lambda title: f"{title}\n{'-' * len(title)}"  # type: ignor
 _ENV.filters["h3"] = lambda title: f"{title}\n{'~' * len(title)}"  # type: ignore
 _ENV.filters["mangle"] = lambda name: _mangle_filename(name)  # type: ignore
 
-_TEMPLATE_RST = _ENV.from_string(
-    """{{ title | h1 }}
+_TEMPLATE_RST = _ENV.from_string("""{{ title | h1 }}
 
 .. lua:currentmodule:: {{ parent_modname }}
 
@@ -39,11 +38,9 @@ _TEMPLATE_RST = _ENV.from_string(
    {{ child_fullname | mangle }}.rst
    {% endfor %}
 {% endif %}
-""".lstrip()
-)
+""".lstrip())
 
-_TEMPLATE_MD = _ENV.from_string(
-    """# {{ title }}
+_TEMPLATE_MD = _ENV.from_string("""# {{ title }}
 
 ```{lua:currentmodule} {{ parent_modname }}
 ```
@@ -62,8 +59,7 @@ _TEMPLATE_MD = _ENV.from_string(
 {% endfor %}
 ```
 {% endif %}
-""".lstrip()
-)
+""".lstrip())
 
 
 def generate(

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/sphinx_lua_ls/autodoc.py

@@ -1069,6 +1069,10 @@ class AutoObjectDirective(AutodocUtilsMixin):
     doctype_override: str | None = None
 
     def run(self):
+        if self.lua_domain.config.backend == "disable":
+            raise self.error(
+                "autoobject requested but the Lua language server is disabled"
+            )
         self.prepare_options()
 
         signatures: list[str] = []

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/sphinx_lua_ls/config.py

@@ -20,7 +20,7 @@ A = _t.ParamSpec("A")
 @dataclass
 class LuaDomainConfig:
     project_root: pathlib.Path
-    backend: _t.Literal["emmylua", "luals"] = "luals"
+    backend: _t.Literal["emmylua", "luals", "disable"] = "luals"
     project_directories: list[pathlib.Path] | None = None
     auto_install: bool = True
     auto_install_location: pathlib.Path | None = None
@@ -188,9 +188,11 @@ def set_options(app: sphinx.application.Sphinx):
 
     if config["lua_ls_backend"] is not None:
         domain_config.backend = _t.cast(
-            _t.Literal["emmylua", "luals"],
+            _t.Literal["emmylua", "luals", "disable"],
             _str_choices(
-                "lua_ls_backend", config["lua_ls_backend"], ["luals", "emmylua"]
+                "lua_ls_backend",
+                config["lua_ls_backend"],
+                ["luals", "emmylua", "disable"],
             ),
         )
     else:

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/sphinx_lua_ls/inherited.py

@@ -59,7 +59,7 @@ class InheritedMembersTransform(SphinxTransform):
 
                 bases = [(base, data) for base in data.bases]
                 while bases:
-                    (base, data) = bases.pop()
+                    base, data = bases.pop()
 
                     resolved_base = self.domain._find_obj(
                         data.base_lookup_modname or "",

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0/sphinx_lua_ls.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-lua-ls
-Version: 3.9.0
+Version: 3.10.0
 Summary: Automatic documentation generation via EmmyLua/LuaLs
 Author-email: Tamika Nomara <taminomara@gmail.com>
 License-Expression: MIT

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/sphinx_lua_ls.egg-info/SOURCES.txt

@@ -61,6 +61,10 @@ test/roots/test-autodoc/Makefile
 test/roots/test-autodoc/conf.py
 test/roots/test-autodoc/index.rst
 test/roots/test-autodoc/make.bat
+test/roots/test-autodoc-disabled/Makefile
+test/roots/test-autodoc-disabled/conf.py
+test/roots/test-autodoc-disabled/index.rst
+test/roots/test-autodoc-disabled/make.bat
 test/roots/test-autodoc-emmylua/Makefile
 test/roots/test-autodoc-emmylua/conf.py
 test/roots/test-autodoc-emmylua/index.rst
@@ -134,6 +138,7 @@ test/roots/test-autodoc/src/nesting.rst
 test/roots/test-autodoc/src/nesting_recursive.rst
 test/roots/test-autodoc/src/object_types.rst
 test/roots/test-autodoc/src/relative_resolve.rst
+test/roots/test-autodoc/src/unknown_object.rst
 test/roots/test-doc/Makefile
 test/roots/test-doc/conf.py
 test/roots/test-doc/index.rst
@@ -154,6 +159,7 @@ test/test_regression/apidoc-rst-sep.yml
 test/test_regression/apidoc-rst.yml
 test/test_regression/autodoc-annotations.html
 test/test_regression/autodoc-autoindex.html
+test/test_regression/autodoc-disabled-index.html
 test/test_regression/autodoc-emmylua-annotations.html
 test/test_regression/autodoc-emmylua-autoindex.html
 test/test_regression/autodoc-emmylua-doctype.html
@@ -185,6 +191,7 @@ test/test_regression/autodoc-roots-no-roots.html
 test/test_regression/autodoc-roots-single-root.html
 test/test_regression/autodoc-settings-no-recursion.html
 test/test_regression/autodoc-settings-simple.html
+test/test_regression/autodoc-unknown_object.html
 test/test_regression/doc-annotations.html
 test/test_regression/doc-autoindex.html
 test/test_regression/doc-directives.html

sphinx_lua_ls-3.10.0/test/roots/test-autodoc/index.rst

@@ -0,0 +1,7 @@
+Test autodoc
+============
+
+.. toctree::
+   :glob:
+
+   src/*

sphinx_lua_ls-3.10.0/test/roots/test-autodoc/src/unknown_object.rst

@@ -0,0 +1,6 @@
+Unknown object
+==============
+
+.. container:: regression
+
+   .. lua:autoobject:: unknown_module.UnknownObject

sphinx_lua_ls-3.10.0/test/roots/test-autodoc-disabled/conf.py

@@ -0,0 +1,7 @@
+project = "Test"
+copyright = "test"
+author = "test"
+
+extensions = ["sphinx_lua_ls"]
+lua_ls_backend = "disable"
+lua_ls_apidoc_roots = {"mod": "api"}

sphinx_lua_ls-3.10.0/test/roots/test-autodoc-disabled/index.rst

@@ -0,0 +1,6 @@
+Test autodoc
+============
+
+.. container:: regression
+
+   .. lua:autoobject:: SomeObject

sphinx_lua_ls-3.10.0/test/roots/test-autodoc-emmylua/index.rst

@@ -0,0 +1,7 @@
+Test autodoc
+============
+
+.. toctree::
+   :glob:
+
+   src/*

sphinx_lua_ls-3.10.0/test/roots/test-doc/index.rst

@@ -0,0 +1,7 @@
+Test documentation
+==================
+
+.. toctree::
+   :glob:
+
+   src/*

sphinx_lua_ls-3.10.0/test/roots/test-intersphinx/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sphinx_lua_ls-3.10.0/test/roots/test-intersphinx/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

sphinx_lua_ls-3.10.0/test/test_regression/autodoc-roots-no-roots.html

@@ -0,0 +1,2 @@
+<div class="regression docutils container">
+</div>

sphinx_lua_ls-3.10.0/test/test_regression/autodoc-unknown_object.html

@@ -0,0 +1,2 @@
+<div class="regression docutils container">
+</div>

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.0}/test/test_regression.py

@@ -54,21 +54,25 @@ def test_intersphinx(app, ver):
 @pytest.mark.sphinx("html", testroot="autodoc")
 @pytest.mark.test_params(shared_result="test_autodoc_regression")
 @pytest.mark.parametrize(
-    "src",
+    "src,messages",
     [
-        "src/annotations.html",
-        "src/autoindex.html",
-        "src/globals.html",
-        "src/member_ordering.html",
-        "src/module_title.html",
-        "src/nested_modules.html",
-        "src/nesting_recursive.html",
-        "src/nesting.html",
-        "src/object_types.html",
-        "src/relative_resolve.html",
+        ("src/annotations.html", []),
+        ("src/autoindex.html", []),
+        ("src/globals.html", []),
+        ("src/member_ordering.html", []),
+        ("src/module_title.html", []),
+        ("src/nested_modules.html", []),
+        ("src/nesting_recursive.html", []),
+        ("src/nesting.html", []),
+        ("src/object_types.html", []),
+        ("src/relative_resolve.html", []),
+        (
+            "src/unknown_object.html",
+            ["ERROR: unknown lua object unknown_module.UnknownObject"],
+        ),
     ],
 )
-def test_autodoc_regression(app, src, file_regression):
+def test_autodoc_regression(app, src, messages, file_regression):
     app.build()
     path = pathlib.Path(app.outdir) / src
     soup = BeautifulSoup(path.read_text("utf8"), "html.parser")
@@ -81,6 +85,10 @@ def test_autodoc_regression(app, src, file_regression):
         encoding="utf8",
     )
 
+    warning = app.warning.getvalue()
+    for message in messages:
+        assert message in warning
+
 
 @pytest.mark.sphinx("html", testroot="autodoc-emmylua")
 @pytest.mark.test_params(shared_result="test_autodoc_regression_emmylua")
@@ -271,3 +279,35 @@ def test_apidoc(app, name, data_regression, file_regression):
         },
         basename=f"apidoc-{name}",
     )
+
+
+@pytest.mark.sphinx("html", testroot="autodoc-disabled")
+@pytest.mark.test_params(shared_result="test_autodoc_disabled")
+@pytest.mark.parametrize(
+    "src,messages",
+    [
+        (
+            "index.html",
+            [
+                "autoobject requested but the Lua language server is disabled",
+                "ERROR: autoobject requested but the Lua language server is disabled",
+            ],
+        ),
+    ],
+)
+def test_autodoc_disabled(app, src, messages, file_regression):
+    app.build()
+    path = pathlib.Path(app.outdir) / src
+    soup = BeautifulSoup(path.read_text("utf8"), "html.parser")
+    content = soup.select_one("div.regression")
+    assert content
+    file_regression.check(
+        content.prettify(),
+        basename="autodoc-disabled-" + pathlib.Path(src).stem,
+        extension=".html",
+        encoding="utf8",
+    )
+
+    warning = app.warning.getvalue()
+    for message in messages:
+        assert message in warning

sphinx_lua_ls-3.9.0/test/roots/test-autodoc/index.rst

@@ -1,15 +0,0 @@
-Test autodoc
-============
-
-.. toctree::
-
-   src/annotations.rst
-   src/autoindex.rst
-   src/globals.rst
-   src/member_ordering.rst
-   src/module_title.rst
-   src/nested_modules.rst
-   src/nesting_recursive.rst
-   src/nesting.rst
-   src/object_types.rst
-   src/relative_resolve.rst

sphinx_lua_ls-3.9.0/test/roots/test-autodoc-emmylua/index.rst

@@ -1,22 +0,0 @@
-Test autodoc
-============
-
-.. toctree::
-
-   src/annotations.rst
-   src/autoindex.rst
-   src/doctype.rst
-   src/globals.rst
-   src/global_tables.rst
-   src/incongruent_export.rst
-   src/member_ordering.rst
-   src/module_title.rst
-   src/module_function.rst
-   src/nested_modules.rst
-   src/nesting_recursive.rst
-   src/nesting.rst
-   src/object_types.rst
-   src/relative_resolve.rst
-   src/require.rst
-   src/signatures.rst
-   src/using.rst

sphinx_lua_ls-3.9.0/test/roots/test-doc/index.rst

@@ -1,11 +0,0 @@
-Test documentation
-==================
-
-.. toctree::
-
-   src/annotations.rst
-   src/autoindex.rst
-   src/directives.rst
-   src/inherited.rst
-   src/modules.rst
-   src/refs.rst