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

{sphinx_lua_ls-3.10.0 → sphinx_lua_ls-3.11.0}/.cl-keeper.yaml

@@ -5,3 +5,5 @@ extra_change_categories_map:
   '(?i)migrating': "migrating"
 extra_change_categories:
   migrating: ""
+severity:
+  ReleaseHasNoChangeCategories: none

{sphinx_lua_ls-3.10.0 → sphinx_lua_ls-3.11.0}/.github/dependabot.yml

@@ -24,3 +24,11 @@ updates:
           - "black"
           - "isort"
           - "pre-commit"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      gh-actions:
+        patterns:
+          - "*"

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

@@ -14,11 +14,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - name: Update pip
@@ -38,7 +38,7 @@ jobs:
       - name: Download EmmyLua for MacOs
         run: python -m sphinx_lua_ls.lua_ls darwin arm --runtime emmylua ~/lua_ls_release/macos-latest
       - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: lua_ls_release
           path: ~/lua_ls_release
@@ -55,9 +55,6 @@ jobs:
           - ubuntu-latest
           - macos-latest
           - windows-latest
-        python-version:
-          - "3.12"
-          - "3.13"
         type:
           - test
         include:
@@ -67,42 +64,30 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout source
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - name: Set up python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Update pip
-        run: python -m pip install --upgrade pip
-      # Tests
-      - name: Install test dependencies
-        if: ${{ matrix.type == 'test' }}
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+      - name: Install dependencies
         run: |
-          python -m pip install . --group test
-          python -m pip install -U sphinx
+          uv tool install poethepoet
+      # Tests
       - name: Download LuaLs
         if: ${{ matrix.type == 'test' }}
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: lua_ls_release
           path: ~/lua_ls_release
-      - name: Check types
-        if: ${{ matrix.type == 'test' }}
-        run: pyright
       - name: Test package
         if: ${{ matrix.type == 'test' }}
-        run: pytest -vv --showlocals --tb=short --color=yes --junit-xml=test-results.xml
+        run: poe ci
         env:
           LUA_LS_CACHE_PATH: ~/lua_ls_release/${{ matrix.os }}
       # Lint
-      - name: Install lint dependencies
-        if: ${{ matrix.type == 'code style' }}
-        run: python -m pip install . --group lint
       - name: Check code style
         if: ${{ matrix.type == 'code style' }}
-        run: pre-commit run -a
+        run: poe lint --color always
   publish_to_pypi:
     name: Publish package to PyPi
     needs:
@@ -117,7 +102,7 @@ jobs:
       id-token: write
     steps:
       - name: Checkout source
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Generate release metadata
@@ -129,11 +114,11 @@ jobs:
           echo "link=${link}" >> $GITHUB_OUTPUT
       - name: Parse Changelog
         id: changelog
-        uses: taminomara/cl-keeper@v0
+        uses: taminomara/cl-keeper@v1
         with:
           version: ${{ github.ref }}
       - name: Set up python 3.12
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: 3.12
       - name: Install build

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

@@ -1,32 +1,24 @@
 repos:
   - repo: local
     hooks:
-      - id: black
-        name: black
+      - id: ruff-check
+        name: ruff check
         language: system
-        entry: black
+        entry: scripts/resolve_venv.sh ruff check --force-exclude
         types_or: [python, pyi]
         require_serial: true
-      - id: isort
-        name: isort
+      - id: ruff-format
+        name: ruff format
         language: system
-        entry: isort --filter-files
+        entry: scripts/resolve_venv.sh ruff format --force-exclude
         types_or: [python, pyi]
         require_serial: true
       - id: clk
         name: changelog keeper
         language: system
-        entry: clk pre-commit-check
+        entry: scripts/resolve_venv.sh 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.10.0 → sphinx_lua_ls-3.11.0}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [3.11.0] - 2026-03-29
+
+- Added config option to print debug logs: `lua_ls_verbose`.
+- Improved error messages related to object lookup errors and added a troubleshooting
+  guide.
+
+## [3.10.1] - 2026-03-29
+
+- Fiexd broken cross-references on the search page.
+
 ## [3.10.0] - 2026-01-29
 
 - Added option to disable running lua-ls (`lua_ls_backend = "disable"`) for cases when
@@ -272,6 +282,8 @@ Initial release.
 [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.10.1]: https://github.com/sphinx-contrib/lua-ls/compare/v3.10.0...v3.10.1
+[3.11.0]: https://github.com/sphinx-contrib/lua-ls/compare/v3.10.1...v3.11.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
@@ -287,4 +299,4 @@ Initial release.
 [@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.10.0...HEAD
+[unreleased]: https://github.com/sphinx-contrib/lua-ls/compare/v3.11.0...HEAD

sphinx_lua_ls-3.11.0/CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing to Sphinx-LuaLs
+
+## Set up your environment
+
+We use [`uv`] and [`poe`] to run tasks, but it is possible to use pure pip as well.
+
+[`uv`]: https://docs.astral.sh/uv/
+[`poe`]: https://poethepoet.natn.io/index.html
+
+### Using pip
+
+1. Create a virtual environment with python `3.12` or newer.
+
+2. Make sure your pip is up to date:
+
+   ```shell
+   pip install -U pip
+   ```
+
+2. Install package in development mode, and install dev dependencies:
+
+   ```shell
+   pip install -e . --group dev
+   ```
+
+3. Install pre-commit hooks:
+
+   ```shell
+   prek install
+   ```
+
+4. [Install `poe`], either globally or in virtual environment:
+
+   ```shell
+   pip install poethepoet
+   ```
+
+[Install `poe`]: https://poethepoet.natn.io/installation.html
+
+5. If you're not on linux, install [EmmyLua Doc Cli].
+
+[EmmyLua Doc Cli]: https://github.com/EmmyLuaLs/emmylua-analyzer-rust/?tab=readme-ov-file#-installation
+
+### Using uv
+
+1. Sync your virtual environment:
+
+   ```shell
+   uv sync
+   ```
+
+2. Install pre-commit hooks:
+
+   ```shell
+   uv run prek install
+   ```
+
+3. [Install `poe`] if you don't have it already:
+
+   ```shell
+   uv tool install poethepoet
+   ```
+
+5. If you're not on linux, install [EmmyLua Doc Cli].
+
+
+## Run tests
+
+We use `poe` for most of the tasks:
+
+```shell
+poe lint  # Lint and fix code style.
+poe test  # Run tests.
+poe test-all  # Run tests for all pythons.
+```
+
+You can see all commands in `poe`'s help:
+
+```shell
+poe --help
+```
+
+
+## Build docs
+
+Just run `sphinx` as usual, nothing special is required:
+
+```shell
+cd docs/
+make html
+```
+
+Sphinx-LuaLs will download the latest version of Lua Language Server for you.
+
+
+## Release
+
+1. Make sure that "Unreleased" section in `changelog.md` is up to date.
+
+2. Run `poe release major|minor|patch` to bump version in changelog
+   and create a release tag.
+
+3. Push a git tag. You'll need a repository admin role to do so.
+
+4. From here, release happens automatically. PyPi package will be uploaded from
+   CI job, and documentation will be updated by Read the Docs build.

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

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

{sphinx_lua_ls-3.10.0 → sphinx_lua_ls-3.11.0}/conftest.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import sys
 
 from sybil import Sybil

{sphinx_lua_ls-3.10.0 → sphinx_lua_ls-3.11.0}/docs/source/conf.py

@@ -29,6 +29,7 @@ lua_ls_backend = "emmylua"
 lua_ls_class_default_function_name = "__init"
 lua_ls_class_default_force_non_colon = True
 lua_ls_class_default_force_return_self = True
+lua_ls_verbose = True
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),

{sphinx_lua_ls-3.10.0 → sphinx_lua_ls-3.11.0}/docs/source/index.rst

@@ -11,19 +11,22 @@ based on `EmmyLua`_ or `LuaLs`_ language servers.
 See an example output: `logging`.
 
 .. toctree::
-   :maxdepth: 1
+    :maxdepth: 1
 
-   installation
-   quickstart
-   directives
-   roles
-   autodoc
-   apidoc
-   settings
-   example
+    installation
+    quickstart
+    directives
+    roles
+    autodoc
+    apidoc
+    settings
+    example
+    troubleshooring
 
 .. toctree::
     :hidden:
     :caption: Links
 
     GitHub <https://github.com/sphinx-contrib/lua-ls/>
+    Issues <https://github.com/sphinx-contrib/lua-ls/issues>
+    Changelog <https://github.com/sphinx-contrib/lua-ls/blob/main/CHANGELOG.md>

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

@@ -244,3 +244,10 @@ Settings
    to use Sphinx's global setting ``maximum_signature_line_length``.
    If ``maximum_signature_line_length`` is also ``None``,
    signature wrapping will be disabled.
+
+.. py:data:: lua_ls_verbose
+   :type: bool
+
+   Prints debug logs from sphinx-lua-ls without raising verbosity level
+   of other Sphinx loggers. Set to ``True`` to see object tree discovered
+   by lua analyzer.

sphinx_lua_ls-3.11.0/docs/source/troubleshooring.rst

@@ -0,0 +1,78 @@
+Troubleshooring
+===============
+
+
+Autodoc can't fund a module or object
+-------------------------------------
+
+1.  Set ``lua_ls_verbose = True`` in ``conf.py`` and run build with ``-E`` (``make html O="-E"``).
+
+#.  Search build log for record ``Lua analysis finished. Found objects:`` and see
+    if object that can't be found appears in the object tree.
+
+#.  If it's there, check spelling and full path of the object. Error message will contain
+    all candidate paths that Sphinx-LuaLs tried when resolving it.
+
+#.  If it's not there, check your documentation markup, EmmyLua/LuaLs settings,
+    and project paths and directories:
+
+    .. tab-set::
+        :sync-group: backend
+
+        .. tab-item:: EmmyLua
+            :sync: emmylua
+
+            a.  Check that :py:data:`lua_ls_project_root` and :py:data:`lua_ls_project_directories`
+                point to the right places.
+
+                You can see how Sphinx-LuaLs launched language server by grepping build
+                log for message ``running lua-language-server with args``.
+
+            #.  Make sure that you have an explicit return at the end of a module.
+
+                If your module only sets global variables, return an empty table from it:
+
+                .. code-block:: lua
+
+                    -- mod.lua
+
+                    --- Module documentation.
+                    return {}
+
+            #.  Alternatively, if your module exports a global variable with the same name,
+                make sure to set its doctype:
+
+                .. code-block:: lua
+
+                    -- mod.lua
+
+                    --- Module documentation.
+                    ---
+                    --- @doctype module
+                    mod = {
+                        -- Module contents.
+                    }
+
+            #.  Make sure that your project directories are listed in ``.emmyrc.json``
+                under ``workspace.workspaceRoots`` and not ``workspace.library``.
+
+        .. tab-item:: LuaLs
+            :sync: luals
+
+            a.  Check that :py:data:`lua_ls_project_root` and :py:data:`lua_ls_project_directories`
+                point to the right places.
+
+                You can see how Sphinx-LuaLs launched language server by grepping build
+                log for message ``running lua-language-server with args``.
+
+            #.  Make sure that you've created a class named after your module, and set its
+                doctype:
+
+                .. code-block:: lua
+
+                    -- mod.lua
+
+                    --- Module documentation.
+                    ---
+                    --- !doctype module
+                    --- @class mod

sphinx_lua_ls-3.11.0/poe_tasks.toml

@@ -0,0 +1,31 @@
+[executor]
+type = "uv"
+
+[tasks.lint]
+help = "Run pre-commit linters"
+cmd = "prek run --all-files"
+
+[tasks.test]
+help = "Run tests"
+cmd = "tox -e 3.14"
+
+[tasks.test-all]
+help = "Run tests for all pythons"
+cmd = "tox p --"
+
+[tasks.doc]
+help = "Build HTML docs"
+cmd = "sphinx-build -b html docs/source docs/build/html -d docs/build/doctrees -j 12 -n"
+
+[tasks.doc-watch]
+help = "Start documentation server and rebuild HTML docs on every change"
+cmd = "sphinx-autobuild docs/source docs/build/html -d docs/build/doctrees --watch . -j 12 -n"
+
+[tasks.release]
+help = "Bump version, create release commit and tag"
+cmd = "clk bump --commit"
+use_exec = true
+
+[tasks.ci]
+help = "For CI job"
+cmd = "tox --colored yes p --skip-env lint --"

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

@@ -25,30 +25,32 @@ dependencies = ["sphinx>=8.0,<10.0", "PyGithub>=1.59,<3.0", "requests~=2.31"]
 
 [dependency-groups]
 dev = [
-    "pytest-cov==7.0.0",
+    "pytest-cov==7.1.0",
     { include-group = "test" },
     { include-group = "lint" },
     { include-group = "doc" },
 ]
 lint = [
-    "black==26.1.0",
-    "isort==7.0.0",
-    "pre-commit==4.5.1",
-    "cl-keeper==0.0.0-b6",
+    "cl-keeper==1.0.0",
+    "prek==0.3.8",
+    "ruff==0.15.8",
 ]
 test = [
     "pyright==1.1.408",
     "pytest==9.0.2",
-    "sybil==9.3.0",
-    "pytest-regressions==2.9.1",
+    "sybil==10.0.1",
+    "pytest-regressions==2.10.0",
     "beautifulsoup4==4.14.3",
     "myst-parser==5.0.0",
+    "tox==4.34.1",
+    "tox-uv==1.29.0",
 ]
 doc = [
-    "sybil==9.3.0",
+    "sybil==10.0.1",
     "furo==2025.12.19",
     "sphinx_design==0.7.0",
     "myst-parser==5.0.0",
+    "sphinx-autobuild==2025.8.25",
 ]
 
 [project.urls]
@@ -89,6 +91,43 @@ reportUnnecessaryIsInstance = "none"
 reportConstantRedefinition = "none"
 reportRedeclaration = "none"
 
-[tool.isort]
-profile = "black"
-skip_gitignore = true
+[tool.ruff]
+exclude = ["examples/docs/*", "test/roots/*"]
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = ["I", "INP", "T20", "PT", "RET", "SIM", "SLOT", "RUF022"]
+ignore = [
+    "E402",   # Module level import not at top of file
+    "E722",   # Do not use bare `except`
+    "E741",   # Ambiguous variable name
+    "E731",   # Do not assign a `lambda` expression, use a `def`
+    "PT015",  # Assertion is always `False`
+    "PT011",  # Too broad error type
+    "PT012",  # `pytest.raises()` block should contain a single simple statement
+    "PT017",  # Found assertion on exception `e` in `except` block
+    "RET505", # Unnecessary `else` after `return` statement
+    "RET506", # Unnecessary `else` after `raise` statement
+    "RET507", # Unnecessary `else` after `continue` statement
+    "RET508", # Unnecessary `else` after `break` statement
+    "SIM103", # Return the negated condition directly
+    "SIM105", # Use `contextlib.suppress` instead of `try`-`except`-`pass`
+    "SIM108", # Use ternary operator instead of `if`-`else`-block
+    "SIM114", # Combine `if` branches using logical `or` operator
+    "SIM118", # Use `key in dict` instead of `key in dict.keys()`
+]
+extend-safe-fixes = [
+    "RUF022", # Sort `__all__`.
+    "PT006",  # Rewrite arguments for `pytest.mark.parametrize`.
+]
+future-annotations = true
+
+[tool.ruff.lint.per-file-ignores]
+"test/**/*" = ["T20", "I002", "SIM102", "SIM117"]
+"docs/**/*" = ["T20", "I002", "INP001"]
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]
+
+[tool.ruff.format]
+docstring-code-format = true

sphinx_lua_ls-3.11.0/scripts/resolve_venv.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -e
+
+if [[ -z $VIRTUAL_ENV && -f .venv/bin/activate ]]; then
+    source .venv/bin/activate
+fi
+
+$@

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

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import fnmatch
 import pathlib
 import re
@@ -10,6 +12,7 @@ import sphinx.builders.html
 import sphinx.domains
 import sphinx.errors
 from sphinx.util import logging
+from sphinx.util.console import get_terminal_width
 from sphinx.util.display import progress_message
 from sphinx.util.fileutil import copy_asset_file
 
@@ -24,7 +27,7 @@ import sphinx_lua_ls.lua_ls
 import sphinx_lua_ls.nodes
 import sphinx_lua_ls.objtree
 import sphinx_lua_ls.utils
-from sphinx_lua_ls._version import __version__, __version_tuple__
+from sphinx_lua_ls._version import __version__, __version_tuple__  # noqa: F401
 from sphinx_lua_ls.pygments import LuaLexer
 
 logger = logging.getLogger("sphinx_lua_ls")
@@ -34,6 +37,7 @@ 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":
+        logger.debug("skipping lua-ls run: backend is 'disabled'")
         return
 
     root_dir = domain.config.project_root
@@ -60,6 +64,9 @@ def run_lua_ls(app: sphinx.application.Sphinx):
                     modified = True
                     break
     if not modified:
+        logger.debug(
+            "skipping lua-ls run: lua files were not modified since previous run"
+        )
         return
 
     cwd = pathlib.Path.cwd()
@@ -74,7 +81,7 @@ def run_lua_ls(app: sphinx.application.Sphinx):
             install=domain.config.auto_install,
             cache_path=domain.config.auto_install_location,
         )
-    except sphinx_lua_ls.lua_ls.LuaLsError as e:
+    except sphinx_lua_ls.lua_ls.LuaLsError:
         raise
     except Exception as e:
         raise sphinx.errors.ExtensionError(str(e)) from e
@@ -128,6 +135,12 @@ def run_lua_ls(app: sphinx.application.Sphinx):
     if parser.runtime_version and not domain.config.lua_version:
         domain.config.lua_version = parser.runtime_version
 
+    logger.debug("Lua analysis finished. Found objects:")
+    logger.debug("-" * get_terminal_width())
+    objtree_s = str(domain.objtree)
+    logger.debug("%s", "<globals>\n" + objtree_s if objtree_s else "<empty>")
+    logger.debug("-" * get_terminal_width())
+
 
 def run_apidoc(
     app: sphinx.application.Sphinx,
@@ -181,6 +194,8 @@ def suppress_auto_ref_warnings(
 ):
     if node["refdomain"] == "lua" and node["reftype"] == "_auto":
         return True
+    else:
+        return None
 
 
 def setup(app: sphinx.application.Sphinx):
@@ -206,6 +221,7 @@ def setup(app: sphinx.application.Sphinx):
     app.add_config_value("lua_ls_class_default_force_non_colon", None, rebuild="env")
     app.add_config_value("lua_ls_class_default_force_return_self", None, rebuild="env")
     app.add_config_value("lua_ls_maximum_signature_line_length", 50, rebuild="env")
+    app.add_config_value("lua_ls_verbose", False, rebuild="")
 
     app.add_directive_to_domain(
         "lua", "autoobject", sphinx_lua_ls.autodoc.AutoObjectDirective