sphinx-lua-ls 3.1.0__tar.gz → 3.2.0__tar.gz

sphinx_lua_ls-3.2.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dev:
+        patterns:
+          - "black"
+          - "furo"
+          - "isort"
+          - "pre-commit"
+          - "pyright"
+          - "pytest_image_diff"
+          - "pytest-cov"
+          - "pytest"
+          - "reportlab"
+          - "sphinx_design"
+          - "svglib"
+          - "sybil"

{sphinx_lua_ls-3.1.0 → sphinx_lua_ls-3.2.0}/.github/workflows/ci.yaml

@@ -155,7 +155,7 @@ jobs:
     name: Build docs
     needs:
       - test
-    if: ${{ !(github.event_name == 'pull_request' && github.event.action == 'closed') }}
+    if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags') && !contains(github.event.ref, '.dev') }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -187,38 +187,6 @@ jobs:
           path: docs/build/html
           include-hidden-files: true
 
-  # Publishes documentation preview and posts a comment to the initiating PR.
-  #
-  # This job runs on all pull request actions. If also runs when a pull request is closed,
-  # in this case it deletes the preview.
-  #
-  # Since the default condition -- `success()` -- only runs if all dependencies succeeded,
-  # we use `!failure() && !cancelled()`, which also runs when any dependencies were skipped.
-  publish_docs_preview:
-    name: Publish docs preview to GitHub Pages
-    needs:
-      - build_docs
-    if: ${{ !failure() && !cancelled() && github.event_name == 'pull_request' }}
-    concurrency:
-      group: publish-docs-${{ github.ref }}
-      cancel-in-progress: true
-    permissions: write-all
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Download artifact
-        if: ${{ needs.build_docs.result == 'success' }}  # only download docs if build wasn't skipped
-        uses: actions/download-artifact@v4
-        with:
-          name: html_output
-          path: docs/build/html
-      - name: Publish HTML
-        uses: rossjrw/pr-preview-action@v1
-        with:
-          source-dir: docs/build/html
-          umbrella-dir: pr-preview
-
   # Builds and publishes production docs.
   #
   # Only runs on tag pushes.

{sphinx_lua_ls-3.1.0 → sphinx_lua_ls-3.2.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v3.2.0
+
+- Updated a few dependencies. Most notably, restricted `sphinx` to `<9`.
+
+- Fixed dashes in types being parsed as type names ([#18] by [@bkoropoff]).
+
+- Added normalization for function syntax (`fun() -> T` is converted to `fun(): T`).
+
+- Done some internal refactorings.
+
+[#18]: https://github.com/taminomara/sphinx-lua-ls/pull/18
+[@bkoropoff]: https://github.com/bkoropoff
+
 ## v3.1.0
 
 - Added pygments lexer for Lua that highlights documentation tags.

{sphinx_lua_ls-3.1.0 → sphinx_lua_ls-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-lua-ls
-Version: 3.1.0
+Version: 3.2.0
 Summary: Automatic documentation generation via EmmyLua/LuaLs
 Author-email: Tamika Nomara <taminomara@gmail.com>
 License-Expression: MIT
@@ -24,28 +24,28 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: sphinx>=8.0
-Requires-Dist: PyGithub~=1.59
+Requires-Dist: sphinx<9.0,>=8.0
+Requires-Dist: PyGithub<3.0,>=1.59
 Requires-Dist: requests~=2.31
 Provides-Extra: dev
-Requires-Dist: pytest-cov~=6.0.0; extra == "dev"
+Requires-Dist: pytest-cov==6.2.1; extra == "dev"
 Requires-Dist: sphinx-lua-ls[doc,lint,test]; extra == "dev"
 Provides-Extra: lint
-Requires-Dist: black~=23.7; extra == "lint"
-Requires-Dist: isort~=5.12; extra == "lint"
-Requires-Dist: pre-commit~=3.8.0; extra == "lint"
+Requires-Dist: black==25.1.0; extra == "lint"
+Requires-Dist: isort==6.0.1; extra == "lint"
+Requires-Dist: pre-commit==4.3.0; extra == "lint"
 Provides-Extra: test
-Requires-Dist: pyright~=1.1; extra == "test"
-Requires-Dist: pytest~=7.4; extra == "test"
-Requires-Dist: sybil~=6.1; extra == "test"
-Requires-Dist: pytest-regressions~=2.7; extra == "test"
-Requires-Dist: beautifulsoup4~=4.13; extra == "test"
-Requires-Dist: myst-parser~=4.0; extra == "test"
+Requires-Dist: pyright==1.1.404; extra == "test"
+Requires-Dist: pytest==8.4.1; extra == "test"
+Requires-Dist: sybil==9.2.0; extra == "test"
+Requires-Dist: pytest-regressions==2.8.2; extra == "test"
+Requires-Dist: beautifulsoup4==4.13.5; extra == "test"
+Requires-Dist: myst-parser==4.0.1; extra == "test"
 Provides-Extra: doc
-Requires-Dist: sybil~=6.1; extra == "doc"
-Requires-Dist: furo>=2024; extra == "doc"
-Requires-Dist: sphinx_design>=0.6; extra == "doc"
-Requires-Dist: myst-parser~=4.0; extra == "doc"
+Requires-Dist: sybil==9.2.0; extra == "doc"
+Requires-Dist: furo==2025.7.19; extra == "doc"
+Requires-Dist: sphinx_design==0.6.1; extra == "doc"
+Requires-Dist: myst-parser==4.0.1; extra == "doc"
 Dynamic: license-file
 
 # Sphinx plugin for Lua and Lua Language Server

{sphinx_lua_ls-3.1.0 → sphinx_lua_ls-3.2.0}/docs/source/roles.rst

@@ -6,7 +6,7 @@ Cross-referencing objects
 
    You can reference any documented object through the :rst:role:`lua:obj` role.
 
-   Given an object path, Lua domain will first search for an object with this path
+   Given an object path, Sphinx-LuaLs will first search for an object with this path
    in the outer-most class, then in the current module, and finally
    in the global namespace.
 
@@ -18,7 +18,6 @@ Cross-referencing objects
    If you specify a fully qualified object name, and would like to hide its prefix,
    you can add a tilde (``~``) to the object's path:
 
-
    .. tab-set::
       :sync-group: lang
 

{sphinx_lua_ls-3.1.0 → sphinx_lua_ls-3.2.0}/pyproject.toml

@@ -22,34 +22,34 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "sphinx>=8.0",
-    "PyGithub~=1.59",
+    "sphinx>=8.0,<9.0",
+    "PyGithub>=1.59,<3.0",
     "requests~=2.31",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "pytest-cov~=6.0.0",
+    "pytest-cov==6.2.1",
     "sphinx-lua-ls[test,lint,doc]",
 ]
 lint = [
-    "black~=23.7",
-    "isort~=5.12",
-    "pre-commit~=3.8.0",
+    "black==25.1.0",
+    "isort==6.0.1",
+    "pre-commit==4.3.0",
 ]
 test = [
-    "pyright~=1.1",
-    "pytest~=7.4",
-    "sybil~=6.1",
-    "pytest-regressions~=2.7",
-    "beautifulsoup4~=4.13",
-    "myst-parser~=4.0"
+    "pyright==1.1.404",
+    "pytest==8.4.1",
+    "sybil==9.2.0",
+    "pytest-regressions==2.8.2",
+    "beautifulsoup4==4.13.5",
+    "myst-parser==4.0.1"
 ]
 doc = [
-    "sybil~=6.1",
-    "furo>=2024",
-    "sphinx_design>=0.6",
-    "myst-parser~=4.0"
+    "sybil==9.2.0",
+    "furo==2025.7.19",
+    "sphinx_design==0.6.1",
+    "myst-parser==4.0.1"
 ]
 
 [project.urls]

sphinx_lua_ls-3.2.0/sphinx_lua_ls/__init__.py

@@ -0,0 +1,217 @@
+import fnmatch
+import pathlib
+import re
+import typing as _t
+
+import sphinx.addnodes
+import sphinx.application
+import sphinx.builders
+import sphinx.builders.html
+import sphinx.domains
+import sphinx.errors
+from sphinx.util.display import progress_message
+from sphinx.util.fileutil import copy_asset_file
+
+import sphinx_lua_ls.apidoc
+import sphinx_lua_ls.autodoc
+import sphinx_lua_ls.autoindex
+import sphinx_lua_ls.config
+import sphinx_lua_ls.domain
+import sphinx_lua_ls.inherited
+import sphinx_lua_ls.intersphinx
+import sphinx_lua_ls.lua_ls
+import sphinx_lua_ls.objtree
+from sphinx_lua_ls._version import __version__, __version_tuple__
+from sphinx_lua_ls.pygments import LuaLexer
+
+
+def run_lua_ls(app: sphinx.application.Sphinx):
+    domain: sphinx_lua_ls.domain.LuaDomain = app.env.get_domain("lua")  # type: ignore
+
+    root_dir = domain.config.project_root
+    project_directories = domain.config.project_directories
+    if project_directories is None:
+        project_directories = [root_dir]
+    project_directories.sort()
+
+    modified = (
+        "objtree" not in domain.data
+        or "objtree_roots" not in domain.data
+        or "objtree_paths" not in domain.data
+        or domain.data["objtree_roots"] != project_directories
+    )
+    if not modified:
+        for path, modtime in domain.data["objtree_paths"].items():
+            if not path.exists() or path.stat().st_mtime_ns > modtime:
+                modified = True
+                break
+    if not modified:
+        for dir in project_directories:
+            for path in dir.rglob("*.lua"):
+                if path not in domain.data["objtree_paths"]:
+                    modified = True
+                    break
+    if not modified:
+        return
+
+    min_version = domain.config.min_version
+    if min_version is None:
+        if domain.config.backend == "luals":
+            min_version = "3.0.0"
+        else:
+            min_version = "0.11.0"
+
+    cwd = pathlib.Path.cwd()
+    try:
+        runner = sphinx_lua_ls.lua_ls.resolve(
+            backend=domain.config.backend,
+            min_version=min_version,
+            cwd=root_dir,
+            reporter=sphinx_lua_ls.lua_ls.SphinxProgressReporter(app.verbosity),
+            install=domain.config.auto_install,
+            cache_path=domain.config.auto_install_location,
+        )
+    except sphinx_lua_ls.lua_ls.LuaLsError as e:
+        raise
+    except Exception as e:
+        raise sphinx.errors.ExtensionError(str(e)) from e
+
+    if domain.config.backend == "luals":
+        parser = sphinx_lua_ls.objtree.LuaLsParser()
+    else:
+        parser = sphinx_lua_ls.objtree.EmmyLuaParser()
+
+    configs = []
+    if (path := pathlib.Path(root_dir, ".emmyrc.json")).exists():
+        configs.append(path)
+    if (path := pathlib.Path(root_dir, ".luarc.json")).exists():
+        configs.append(path)
+    parser.files.update(configs)
+
+    for dir in project_directories:
+        try:
+            relpath = dir.relative_to(cwd, walk_up=True)
+        except ValueError:
+            relpath = dir
+        with progress_message(f"running lua language server in {relpath or '.'}"):
+            parser.class_default_function_name = (
+                domain.config.class_default_function_name
+            )
+            parser.class_default_force_non_colon = (
+                domain.config.class_default_force_non_colon
+            )
+            parser.class_default_force_return_self = (
+                domain.config.class_default_force_return_self
+            )
+            parser.parse(runner.run(dir, configs=configs), dir)
+            parser.files.update(map(pathlib.Path, dir.rglob("*.lua")))
+
+    domain.objtree = parser.root
+    domain.data["objtree_roots"] = project_directories
+    domain.data["objtree_paths"] = {p: p.stat().st_mtime_ns for p in parser.files}
+
+    if parser.runtime_version and not domain.config.lua_version:
+        domain.config.lua_version = parser.runtime_version
+
+
+def run_apidoc(
+    app: sphinx.application.Sphinx,
+):
+    domain = _t.cast(sphinx_lua_ls.domain.LuaDomain, app.env.get_domain("lua"))
+    cwd = pathlib.Path.cwd()
+    for name, params in domain.config.apidoc_roots.items():
+        try:
+            relpath = params["path"].relative_to(cwd, walk_up=True)
+        except ValueError:
+            relpath = params["path"]
+        with progress_message(f"running lua apidoc in {relpath or '.'}"):
+            ignored_modules = params["ignored_modules"]
+            if ignored_modules:
+                mod_filter = re.compile(
+                    "|".join(f"(?:{fnmatch.translate(e)})" for e in ignored_modules)
+                ).match
+            else:
+                mod_filter = lambda s: False
+            sphinx_lua_ls.apidoc.generate(
+                outdir=app.outdir,
+                domain=domain,
+                dir=params["path"],
+                fullname=name,
+                objtree=domain.objtree,
+                options=params["options"],
+                depth=params["max_depth"],
+                mod_filter=mod_filter,
+                format=params["format"],
+                separate_members=params["separate_members"],
+            )
+
+
+def copy_asset_files(app: sphinx.application.Sphinx, exc: Exception | None):
+    if isinstance(app.builder, sphinx.builders.html.StandaloneHTMLBuilder) and not exc:
+        custom_file = pathlib.Path(__file__).parent / "static/lua.css"
+        static_dir = app.outdir / "_static"
+        copy_asset_file(custom_file, static_dir)
+
+
+def suppress_auto_ref_warnings(
+    app: sphinx.application.Sphinx,
+    domain: sphinx.domains.Domain,
+    node: sphinx.addnodes.pending_xref,
+):
+    if node["refdomain"] == "lua" and node["reftype"] == "_auto":
+        return True
+
+
+def setup(app: sphinx.application.Sphinx):
+    app.add_domain(sphinx_lua_ls.domain.LuaDomain)
+
+    app.add_config_value("lua_ls_backend", None, rebuild="env")
+    app.add_config_value("lua_ls_project_root", None, rebuild="env")
+    app.add_config_value("lua_ls_project_directories", None, rebuild="env")
+    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_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="")
+    app.add_config_value("lua_ls_apidoc_default_options", None, rebuild="")
+    app.add_config_value("lua_ls_apidoc_max_depth", None, rebuild="")
+    app.add_config_value("lua_ls_apidoc_ignored_modules", None, rebuild="")
+    app.add_config_value("lua_ls_apidoc_format", None, rebuild="")
+    app.add_config_value("lua_ls_apidoc_separate_members", None, rebuild="")
+    app.add_config_value("lua_ls_class_default_function_name", None, rebuild="env")
+    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_directive_to_domain(
+        "lua", "autoobject", sphinx_lua_ls.autodoc.AutoObjectDirective
+    )
+    app.add_directive_to_domain(
+        "lua", "autoindex", sphinx_lua_ls.autoindex.AutoIndexDirective
+    )
+    app.add_directive_to_domain(
+        "lua",
+        "other-inherited-members",
+        sphinx_lua_ls.inherited.InheritedMembersDirective,
+    )
+
+    app.connect("builder-inited", sphinx_lua_ls.config.set_options)
+    app.connect("builder-inited", run_lua_ls)
+    app.connect("builder-inited", run_apidoc)
+    app.connect("missing-reference", sphinx_lua_ls.intersphinx.resolve_std_reference)
+    app.connect("build-finished", copy_asset_files)
+    app.connect("warn-missing-reference", suppress_auto_ref_warnings)
+
+    app.add_post_transform(sphinx_lua_ls.autoindex.AutoIndexTransform)
+    app.add_post_transform(sphinx_lua_ls.inherited.InheritedMembersTransform)
+
+    app.add_lexer("lua", LuaLexer)
+
+    app.add_css_file("lua.css")
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

{sphinx_lua_ls-3.1.0 → sphinx_lua_ls-3.2.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.1.0'
-__version_tuple__ = version_tuple = (3, 1, 0)
+__version__ = version = '3.2.0'
+__version_tuple__ = version_tuple = (3, 2, 0)
 
-__commit_id__ = commit_id = 'g26ca4bce6'
+__commit_id__ = commit_id = 'g226dbf0db'

{sphinx_lua_ls-3.1.0 → sphinx_lua_ls-3.2.0}/sphinx_lua_ls/autodoc.py

@@ -78,9 +78,11 @@ def _iter_children(
         case "bysource":
             children.sort(
                 key=lambda ch: (
-                    str(ch[1].docstring_file or "~")
-                    if not _FIX_FLAKY_ALIAS_TESTS
-                    else "",
+                    (
+                        str(ch[1].docstring_file or "~")
+                        if not _FIX_FLAKY_ALIAS_TESTS
+                        else ""
+                    ),
                     ch[1].line or math.inf,
                     ch[0],
                 )
@@ -465,7 +467,7 @@ class AutodocUtilsMixin(sphinx_lua_ls.domain.LuaContextManagerMixin):
 
     @property
     def objtree(self) -> Object:
-        return self.env.domaindata["lua"]["objtree"]
+        return self.lua_domain.objtree
 
     @functools.cached_property
     def parent(self):
@@ -504,13 +506,10 @@ class AutodocDirectiveMixin(AutodocUtilsMixin):
                 and nodes
                 and isinstance(nodes[0], docutils.nodes.paragraph)
             ):
-                objects: dict[
-                    str, sphinx_lua_ls.domain.LuaDomain.ObjectEntry
-                ] = self.env.domaindata["lua"]["objects"]
-                if fullname in objects:
-                    data = objects[fullname]
+                if fullname in self.lua_domain.objects:
+                    data = self.lua_domain.objects[fullname]
                     if not data.synopsis:
-                        objects[fullname] = dataclasses.replace(
+                        self.lua_domain.objects[fullname] = dataclasses.replace(
                             data, synopsis=nodes[0].astext()
                         )
 
@@ -892,7 +891,6 @@ class LuaModule(AutodocDirectiveMixin, sphinx_lua_ls.domain.LuaModule):
 
         api_docs = docutils.nodes.section("", names=[])
 
-        domain: sphinx_lua_ls.domain.LuaDomain = self.env.get_domain("lua")  # type: ignore
         prev_title = None
         for name, child in _iter_children(
             self.root, self.objtree, self.parent, self.options
@@ -902,7 +900,7 @@ class LuaModule(AutodocDirectiveMixin, sphinx_lua_ls.domain.LuaModule):
                 if child.is_toplevel:
                     title = "Global"
                 else:
-                    title = domain.object_types[kind.value].lname.title()
+                    title = self.lua_domain.object_types[kind.value].lname.title()
 
                 if prev_title != title:
                     if api_docs.children:
@@ -941,9 +939,7 @@ class AutoObjectDirective(AutodocUtilsMixin):
     has_content = True
 
     def run(self):
-        for name, option in self.env.domaindata["lua"]["config"][
-            "default_options"
-        ].items():
+        for name, option in self.lua_domain.config.default_options.items():
             if name not in self.options:
                 self.options[name] = option