Settings¶

lua_ls_project_root: str¶: Path to a directory with .luarc.json file, relative to the location of conf.py. Lua analyzer will be launched from here.

lua_ls_project_directories: list[str]¶

List of directories where lua analyzer will run, relative to lua_ls_project_root.

By default, consists of a single lua_ls_project_root.

lua_ls_backend: str¶: Controls which lua analyzer is used. Can be either "emmylua" or "luals".

lua_ls_auto_install: bool¶: Controls whether Sphinx-LuaLs should try downloading lua analyzer (LuaLs or EmmyLua) from github if it isn’t installed already. This setting is enabled by default.

lua_ls_auto_install_location: str¶: Controls where the lua analyzer will be installed. By default, Sphinx-LuaLs uses a folder in the temporary directory provided by the os. For unix, it is /tmp/python_lua_ls_cache.

lua_ls_min_version: str¶: Controls the minimal version of the used lua analyzer.

lua_ls_default_options: dict[str, str]¶

Default values for directive options. You can override member ordering or enable documentation for undocumented or private members from here. For example:

lua_ls_default_options = {
    # Enable documentation for object's members.
    # Empty string means documenting all members with non-empty description.
    "members": "",
    # Set ordering of automatically generated content to alphabetical.
    "member-order": "alphabetical",
    # And so on...
}

class_default_function_name: str¶

Allows specifying which class method represents a class constructor.

Class constructors are documented separately, depending on lua:autoobject:class-doc-from and lua:autoobject:class-signature options.

If using EmmyLua as lua analyzer, this option will be inferred from .emmyrc.json.

class_default_force_non_colon¶

If true, Sphinx-LuaLs will remove self from class constructor’s signature.

If using EmmyLua as lua analyzer, this option will be inferred from .emmyrc.json.

class_default_force_return_self¶

If true, Sphinx-LuaLs will replace class constructor’s return type with self.

If using EmmyLua as lua analyzer, this option will be inferred from .emmyrc.json.

lua_ls_lua_version: str¶

Controls which documentation version is used when linking to standard library functions. Does not otherwise affect parsing or generation.

Can be either "5.1", "5.2", "5.3", "5.4", or "jit".

By default, Sphinx-LuaLs will choose this setting based on your emmyrc.json/luarc.json file.

lua_ls_apidoc_roots: dict[str, str | dict[str, Any]]¶

Roots for apidoc. Keys are full module names that should be generated, and values are directories (relative to the location of conf.py) where .rst files are placed.

Additionally, you can override other apidoc settings for each root. For this, make root’s value a dictionary with keys path, max_depth, options, ignored_modules, separate_members, and format:

lua_ls_apidoc_roots = {
    "moduleName": {
        "path": "moduleDirectory",
        "max_depth": 2,
        "options": {
            "undoc-members": "",
        },
        "format": "md",
    },
}

lua_ls_apidoc_default_options: dict[str, str]¶: Default options for objects documented via apidoc. Override lua_ls_default_options.

lua_ls_apidoc_max_depth: int¶

Maximum nesting level for files. Submodules that are deeper than this level will not get their own file, and instead will be generated inline.

Default value is 4.

lua_ls_apidoc_separate_members: bool¶

If set to True, module members will be rendered on separate pages.

Warning

Windows users

This option might not work correctly on case-insensitive file systems.

It will generate a separate file for every member of a module; if there are members that only differ in case (i.e. Class vs class), one of them will overwrite the file for another.

If you’re on Windows, and you experience difficulties because of it, make your source and output directories case-insensitive and add the following hack to your conf.py:

# This evil code forces Python to treat
# windows filenames as case-sensitive.
import pathlib
pathlib.PureWindowsPath._str_normcase = property(str)

lua_ls_apidoc_ignored_modules: list[str]¶

List of full submodule names that should be ignored while generating APIs. Submodules can contain fnmatch style globs.

For example, the following setting

lua_ls_apidoc_roots = {
    "moduleName": "moduleDirectory",
}

lua_ls_apidoc_ignored_modules = [
   "moduleName.submoduleName"
]

will generate API for module moduleName, but will not include moduleName.submoduleName.

lua_ls_apidoc_format: str¶: Format for generated files. Can be either "rst" or "md".

lua_ls_maximum_signature_line_length: int | None¶

Controls maximum width after which long signatures will be wrapped.

Default value is 50, which is suitable for most Sphinx themes.

Setting this value to None will cause signature formatter to use Sphinx’s global setting maximum_signature_line_length. If maximum_signature_line_length is also None, signature wrapping will be disabled.