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

{sphinx_lua_ls-3.10.1 → 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.1 → sphinx_lua_ls-3.11.0}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [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.
@@ -277,6 +283,7 @@ Initial release.
 [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
@@ -292,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.1...HEAD
+[unreleased]: https://github.com/sphinx-contrib/lua-ls/compare/v3.11.0...HEAD

{sphinx_lua_ls-3.10.1/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.1
+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.1 → 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.1 → sphinx_lua_ls-3.11.0}/docs/source/index.rst

@@ -21,6 +21,7 @@ See an example output: `logging`.
     apidoc
     settings
     example
+    troubleshooring
 
 .. toctree::
     :hidden:

{sphinx_lua_ls-3.10.1 → 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.10.1 → sphinx_lua_ls-3.11.0}/sphinx_lua_ls/__init__.py

@@ -12,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
 
@@ -36,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
@@ -62,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()
@@ -130,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,
@@ -210,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

{sphinx_lua_ls-3.10.1 → sphinx_lua_ls-3.11.0}/sphinx_lua_ls/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.10.1'
-__version_tuple__ = version_tuple = (3, 10, 1)
+__version__ = version = '3.11.0'
+__version_tuple__ = version_tuple = (3, 11, 0)
 
-__commit_id__ = commit_id = 'ga3c6199fd'
+__commit_id__ = commit_id = 'gf59390e32'

{sphinx_lua_ls-3.10.1 → sphinx_lua_ls-3.11.0}/sphinx_lua_ls/apidoc.py

@@ -145,9 +145,14 @@ def _generate(
     is_global: bool = False,
     parent_modname: str | None = None,
 ):
-    obj = objtree.find(fullname)
+    obj, modname, classname, objname = objtree.find_path(fullname)
     if not obj:
-        raise sphinx.errors.ConfigError(f"can't find module {fullname}")
+        parent = ".".join(filter(None, [modname, classname])) or "<global namespace>"
+        msg = f"unknown lua object {fullname}:\n"
+        msg += f"  {parent} has no item {objname!r}\n"
+        msg += "Hint: set `lua_ls_verbose = True` in conf.py to see all objects exported by lua analyzer.\n"
+        msg += "Hint: see troubleshooting guide at https://sphinx-lua-ls.readthedocs.io/en/latest/troubleshooring.html"
+        raise sphinx.errors.ConfigError(msg)
 
     autodoc_options = options.copy()
     for name, value in obj.parsed_options.items():

{sphinx_lua_ls-3.10.1 → sphinx_lua_ls-3.11.0}/sphinx_lua_ls/autodoc.py

@@ -1099,8 +1099,6 @@ class AutoObjectDirective(AutodocUtilsMixin):
             raise self.error("got an empty object name")
 
         found = self.get_root(name)
-        if not found:
-            raise self.error(f"unknown lua object {name}")
 
         root, modname, classname, objname = found
 
@@ -1131,7 +1129,7 @@ class AutoObjectDirective(AutodocUtilsMixin):
     def get_signatures(self) -> list[str]:
         return sphinx_lua_ls.domain.LuaObject.get_signatures(self)  # type: ignore
 
-    def get_root(self, name: str) -> tuple[Object, str, str, str] | None:
+    def get_root(self, name: str) -> tuple[Object, str, str, str]:
         modname = self.options.get("module", self.env.ref_context.get("lua:module"))
         if "module" in self.options:
             classname = ""
@@ -1144,11 +1142,25 @@ class AutoObjectDirective(AutodocUtilsMixin):
             ".".join(filter(None, [name])),
         ]
 
+        attempts: list[tuple[str, str, str, str]] = []
+
         for candidate in candidates:
-            if found := self.objtree.find_path(candidate):
-                return found
+            obj, modname, classname, objname = self.objtree.find_path(candidate)
+            if obj:
+                return obj, modname, classname, objname
+            else:
+                attempts.append((candidate, modname, classname, objname))
+
+        msg = f"unknown lua object {name}:\n"
+        for candidate, modname, classname, objname in attempts:
+            parent = (
+                ".".join(filter(None, [modname, classname])) or "<global namespace>"
+            )
+            msg += f"  Trying as {candidate}: {parent} has no item {objname!r}\n"
+        msg += "Hint: set `lua_ls_verbose = True` in conf.py to see all objects exported by lua analyzer.\n"
+        msg += "Hint: see troubleshooting guide at https://sphinx-lua-ls.readthedocs.io/en/latest/troubleshooring.html"
 
-        return None
+        raise self.error(msg)
 
 
 class AutoFunctionDirective(AutoObjectDirective):

{sphinx_lua_ls-3.10.1 → sphinx_lua_ls-3.11.0}/sphinx_lua_ls/config.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import dataclasses
 import pathlib
 import re
+import sys
 import typing as _t
 from dataclasses import dataclass
 
@@ -41,6 +42,7 @@ class LuaDomainConfig:
     class_default_force_non_colon: bool = False
     class_default_force_return_self: bool = False
     maximum_signature_line_length: int | None = 50
+    verbose: bool = False
 
 
 def _type(name: str, value, types: _t.Type[T] | tuple[_t.Type[T], ...]) -> T:
@@ -326,5 +328,18 @@ def set_options(app: sphinx.application.Sphinx):
             (int, type(None)),
         )
 
+    if config["lua_ls_verbose"] is not None:
+        domain_config.verbose = _type("lua_ls_verbose", config["lua_ls_verbose"], bool)
+        if domain_config.verbose:
+            app.verbosity = max(app.verbosity, 1)
+            root_logger = logging.getLogger("sphinx_lua_ls")
+            root_logger.logger.propagate = False
+            handler = logging.NewLineStreamHandler(
+                logging.SafeEncodingWriter(sys.stdout)
+            )
+            handler.setFormatter(logging.ColorizeFormatter())
+            root_logger.logger.addHandler(handler)
+            root_logger.setLevel("DEBUG")
+
     domain = _t.cast(sphinx_lua_ls.domain.LuaDomain, app.env.get_domain("lua"))
     domain.config = domain_config

{sphinx_lua_ls-3.10.1 → sphinx_lua_ls-3.11.0}/sphinx_lua_ls/objtree.py

@@ -362,38 +362,25 @@ class Object(DocstringMixin):
         return self.__class__.__name__
 
     def __str__(self) -> str:
-        res = ""
-
-        res += self._print_object()
-
-        if self.is_deprecated:
-            res += " (deprecated)"
-        if self.is_async:
-            res += " (async)"
-        if self.is_nodiscard:
-            res += " (nodiscard)"
-
-        tail = self._print_object_tail()
-
-        for name, ch in self.children.items():
-            first, *rest = str(ch).splitlines()
-            if rest:
-                rest = "\n  " + "\n  ".join(rest)
-            else:
-                rest = ""
-            res += f"\n  {name} {first}{rest}"
-
-        if self.children and tail:
-            res += "\n"
-        res += tail
-
-        return res
-
-    def _print_object(self) -> str:
-        return "{"
-
-    def _print_object_tail(self) -> str:
-        return "}"
+        lines: list[str] = []
+        self._print_children_tree(lines, "")
+        return "\n".join(lines)
+
+    def _print_children_tree(self, lines: list[str], prefix: str):
+        items = list(self.children.items())
+        for i, (name, ch) in enumerate(items):
+            is_last = i == len(items) - 1
+            connector = "└── " if is_last else "├── "
+            continuation = "    " if is_last else "│   "
+
+            desc = f"{prefix}{connector}"
+            if ch.kind:
+                desc += f"{ch.kind.value} "
+            desc += name
+            lines.append(desc)
+
+            ch_prefix = prefix + continuation
+            ch._print_children_tree(lines, ch_prefix)
 
     def find(self, path: str) -> Object | None:
         """
@@ -413,7 +400,7 @@ class Object(DocstringMixin):
             root = root.children[name]
         return root
 
-    def find_path(self, path: str) -> tuple[Object, str, str, str] | None:
+    def find_path(self, path: str) -> tuple[Object | None, str, str, str]:
         """
         Find an object and return a path to it.
 
@@ -433,7 +420,7 @@ class Object(DocstringMixin):
 
         for name in path.split("."):
             if name not in root.children:
-                return None
+                return None, ".".join(modname), ".".join(classname), name
 
             root = root.children[name]
 
@@ -478,13 +465,6 @@ class Data(Object):
         else:
             return None
 
-    def _print_object(self) -> str:
-        lit = f" = {self.lit}" if self.lit else ""
-        return f": {self.type}{lit}"
-
-    def _print_object_tail(self) -> str:
-        return ""
-
 
 @dataclass(kw_only=True, repr=False, eq=False)
 class Table(Object):
@@ -505,12 +485,6 @@ class Table(Object):
         else:
             return None
 
-    def _print_object(self) -> str:
-        return "= table {"
-
-    def _print_object_tail(self) -> str:
-        return "}"
-
 
 @dataclass(kw_only=True, repr=False, eq=False)
 class Function(Object):
@@ -548,19 +522,6 @@ class Function(Object):
         else:
             return None
 
-    def _print_object(self) -> str:
-        params = ", ".join(map(str, self.params))
-        generics = ", ".join(map(str, self.generics))
-        if generics:
-            generics = f"<{generics}>"
-        returns = ", ".join(map(str, self.returns))
-        if returns:
-            returns = " -> " + returns
-        return f"= function{generics}({params}){returns}"
-
-    def _print_object_tail(self) -> str:
-        return ""
-
 
 @dataclass(kw_only=True, repr=False, eq=False)
 class Class(Object):
@@ -595,15 +556,6 @@ class Class(Object):
         else:
             return None
 
-    def _print_object(self) -> str:
-        generics = ", ".join(map(str, self.generics))
-        if generics:
-            generics = f"<{generics}>"
-        return f"= class{generics}({', '.join(self.bases)})"
-
-    def _print_object_tail(self) -> str:
-        return ""
-
 
 @dataclass(kw_only=True, repr=False, eq=False)
 class Alias(Object):
@@ -632,15 +584,6 @@ class Alias(Object):
         else:
             return None
 
-    def _print_object(self) -> str:
-        generics = ", ".join(map(str, self.generics))
-        if generics:
-            generics = f"<{generics}>"
-        return f"= alias{generics}({self.type})"
-
-    def _print_object_tail(self) -> str:
-        return ""
-
 
 @dataclass(kw_only=True, repr=False, eq=False)
 class Enum(Object):
@@ -669,15 +612,6 @@ class Enum(Object):
         else:
             return None
 
-    def _print_object(self) -> str:
-        generics = ", ".join(map(str, self.generics))
-        if generics:
-            generics = f"<{generics}>"
-        return f"= enum{generics}({self.type})"
-
-    def _print_object_tail(self) -> str:
-        return ""
-
 
 class Parser:
     #: Lua version used by this runtime.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-lua-ls
-Version: 3.10.1
+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.1 → sphinx_lua_ls-3.11.0}/sphinx_lua_ls.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ docs/source/installation.rst
 docs/source/quickstart.rst
 docs/source/roles.rst
 docs/source/settings.rst
+docs/source/troubleshooring.rst
 docs/source/_extra/robots.txt
 docs/source/example/.emmyrc.json
 docs/source/example/logging.lua