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

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.1}/.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.9.0 → sphinx_lua_ls-3.10.1}/.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
@@ -126,15 +111,14 @@ 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@v1
         with:
-          version: ${{ steps.metadata.outputs.version }}
+          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
@@ -150,11 +134,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.1}/.pre-commit-config.yaml

@@ -1,18 +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: scripts/resolve_venv.sh clk pre-commit-check
+        require_serial: true
+        types_or: [toml, yaml, markdown]
   - 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.1}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [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
+  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 +260,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 +275,8 @@ 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.10.1]: https://github.com/sphinx-contrib/lua-ls/compare/v3.10.0...v3.10.1
 [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 +289,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.1...HEAD

sphinx_lua_ls-3.10.1/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.9.0/sphinx_lua_ls.egg-info → sphinx_lua_ls-3.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-lua-ls
-Version: 3.9.0
+Version: 3.10.1
 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.1}/conftest.py

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

{sphinx_lua_ls-3.9.0 → sphinx_lua_ls-3.10.1}/docs/source/index.rst

@@ -11,19 +11,21 @@ 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
 
 .. 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.9.0 → sphinx_lua_ls-3.10.1}/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.10.1/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.1/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "sphinx-lua-ls"
+authors = [{ name = "Tamika Nomara", email = "taminomara@gmail.com" }]
+description = "Automatic documentation generation via EmmyLua/LuaLs"
+dynamic = ["version"]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+    "Framework :: Sphinx",
+    "Framework :: Sphinx :: Domain",
+    "Framework :: Sphinx :: Extension",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Documentation",
+    "Topic :: Documentation :: Sphinx",
+    "Typing :: Typed",
+]
+dependencies = ["sphinx>=8.0,<10.0", "PyGithub>=1.59,<3.0", "requests~=2.31"]
+
+[dependency-groups]
+dev = [
+    "pytest-cov==7.1.0",
+    { include-group = "test" },
+    { include-group = "lint" },
+    { include-group = "doc" },
+]
+lint = [
+    "cl-keeper==1.0.0",
+    "prek==0.3.8",
+    "ruff==0.15.8",
+]
+test = [
+    "pyright==1.1.408",
+    "pytest==9.0.2",
+    "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==10.0.1",
+    "furo==2025.12.19",
+    "sphinx_design==0.7.0",
+    "myst-parser==5.0.0",
+    "sphinx-autobuild==2025.8.25",
+]
+
+[project.urls]
+Documentation = "https://sphinx-lua-ls.readthedocs.io/en/stable/"
+Issues = "https://github.com/sphinx-contrib/lua-ls/issues"
+Source = "https://github.com/sphinx-contrib/lua-ls/"
+Changelog = "https://github.com/sphinx-contrib/lua-ls/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["setuptools>=60", "setuptools_scm[toml]>=8", "wheel>=0.40"]
+
+[tool.setuptools_scm]
+write_to = "sphinx_lua_ls/_version.py"
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = ["--strict-markers", "-p no:doctest"]
+testpaths = ["test", "sphinx_lua_ls", "docs"]
+
+[tool.pyright]
+include = ["sphinx_lua_ls"]
+exclude = ["**/__pycache__"]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+pythonPlatform = "All"
+
+# deprecateTypingAliases = true
+reportUnnecessaryTypeIgnoreComment = "warning"
+reportUnusedFunction = "none"
+reportPrivateUsage = "none"
+reportMissingParameterType = "none"
+reportUnknownParameterType = "none"
+reportUnknownVariableType = "none"
+reportUnknownMemberType = "none"
+reportUnknownArgumentType = "none"
+reportUnknownLambdaType = "none"
+reportUnnecessaryIsInstance = "none"
+reportConstantRedefinition = "none"
+reportRedeclaration = "none"
+
+[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.10.1/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.9.0 → sphinx_lua_ls-3.10.1}/sphinx_lua_ls/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import fnmatch
 import pathlib
 import re
@@ -24,7 +26,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")
@@ -33,6 +35,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:
@@ -71,7 +76,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
@@ -130,6 +135,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:
@@ -172,6 +183,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):

sphinx_lua_ls-3.10.1/sphinx_lua_ls/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+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)
+
+__commit_id__ = commit_id = 'ga3c6199fd'

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

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import pathlib
 import subprocess