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".