Installation

You’ll need a Python installation and a Sphinx project to start with Sphinx-LuaLs.

If you’re new to Python and Sphinx

1. Installing Python

   We recommend using PyEnv to manage python installations on your system.

   Similar to LuaRocks, it creates executables for Python, Pip (Package Installer for Python), and other tools. When run, these executables determine which Python environment to use, and invoke the appropriate command.

   Following its installation guide, install PyEnv, configure your shell, and install build dependencies.

   Make sure that PyEnv shims are in your path by checking them with which:

   $ which python
   /home/user/.pyenv/shims/python
   $ which pip
   /home/user/.pyenv/shims/pip
   

   Once ready, you can install Python 3.12:

   $ pyenv install 3.12.2
   

   To avoid installing Python packages globally, we recommend using virtual environments. It is a good practice to create a separate environment for each project:

   $ pyenv virtualenv 3.12.2 my-project
   

   Once a new environment is created, you’ll need to activate it. Navigate to your project directory and run the following command:

   $ pyenv local my-project
   

   This will create a file called .python-version. Every time you run an executable that was installed by PyEnv, it will look for a .python-version file to determine which environment to use. Thus, when running Python from your project’s directory, it will always use the right virtual environment.

2. Installing Sphinx

   You can now install Sphinx using Pip:

   $ pip install sphinx
   

   To make your life easier, you can create a file named requirements.txt, and list all of the dependencies there:

   $ echo "sphinx~=8.0" > requirements.txt
   

   Now, you can install all dependencies at once:

   $ pip install -r requirements.txt
   

3. Creating a Sphinx project

   Sphinx comes with a tool for creating new projects. Make a directory for your documentation and run the sphinx-quickstart command in it:

   $ mkdir docs/
   $ cd docs/
   $ sphinx-quickstart
   

   Once finished, you’ll see several files generated. Makefile contains commands to build documentation, conf.py contains configuration, and index.rst is the main document.

   Try building documentation and see the results:

   $ make html
   $ open build/html/index.html
   

1. Install sphinx-lua-ls using Pip:

   $ pip install sphinx-lua-ls
   

2. Add it to the extensions list in your conf.py, and specify the location of your Lua project:

   extensions = [
       "sphinx_lua_ls",
   ]
   
   # Path to the folder containing the `.emmyrc.json`/`.luarc.json` file,
   # relative to the directory with `conf.py`.
   lua_ls_project_root = "../"
   

3. Configure which language analyzer you want to use:

   EmmyLua

   Set lua_ls_backend to "emmylua" in your conf.py:

   lua_ls_backend = "emmylua"
   

   Note

   If you’re on Linux x64, Windows x64, or MacOs arm, Sphinx-LuaLs will download EmmyLua’s documentation tool automatically. Otherwise, you’ll need to install emmylua_doc_cli manually, see instructions at github.

   Tip

   Add the following settings to your .emmyrc.json to enable completion of documentation tags specific to Sphinx-LuaLs:

   {
      "diagnostics": {
         "enables": ["unknown-doc-tag"]
      },
      "doc": {
         "knownTags": ["doctype", "doc"]
      }
   }
   

   LuaLs

   Set lua_ls_backend to "luals" in your conf.py:

   lua_ls_backend = "luals"
   

4. If you plan to use Markdown in code comments, install the MySt plugin for Sphinx and add it to the extensions list in your conf.py.