How To Integrate Esbonio with Emacs¶

This guide covers how to setup esbonio with Emacs using the two main language client implementations:

eglot a mimialistic implementation, relies on built-in functionality where possible. Built into Emacs since v29.1
lsp-mode integrates well with third party packages like treemacs and helm.

Installation¶

Note

The esbonio Python package does not need to be installed into the same environment as your project dependencies. A single, global installation is all that is required.

It’s recommended to install the language server using a tool like uv:

uv tool install esbonio

or pipx:

pipx install esbonio

Alternatively, you can use pip to install esbonio into a virtual environment of your choosing. However you decide to install the server, the esbonio command must be available on your PATH:

$ esbonio --help
usage: esbonio [-h] [--version] {server} ...

The Esbonio language server

options:
  -h, --help  show this help message and exit
  --version   print the current version and exit.

commands:
  {server}
    server    launch the esbonio language server

The esbonio.el package provides the necessary “glue code” to integrate esbonio with both the eglot and lsp-mode clients.

eglot

(use-package esbonio
  :vc (esbonio :url "https://github.com/swyddfa/esbonio.el" :rev "main")
  :hook ((rst-mode . esbonio-eglot-ensure)))

lsp-mode

(use-package esbonio
  :vc (esbonio :url "https://github.com/swyddfa/esbonio.el" :rev "main")
  :hook ((rst-mode . esbonio-lsp-deferred)))  ;; or `esbonio-lsp'

Configuration¶

It’s recommended to store as many project-specific options as possible in your pyproject.toml file

[tool.esbonio.sphinx]
buildCommand = ["sphinx-build", "-M", "html", "docs", "docs/_build"]
pythonCommand = ["uv", "run", "python"]

Tip

See How To Configure the Sphinx Build Environment and How To Configure the Sphinx Build guides for more examples of these settings.

However for options that are only applicable to your setup (e.g. logging), configuration options can also be set through Emacs itself.

eglot

Settings can be provided through setting eglot-workspace-configuration in a .dir-locals.el file in the root of your workspace.

((rst-mode
  . ((eglot-workspace-configuration
      . ((esbonio
         . ((logging
             . ((level . "debug"))))))))))

lsp-mode

Setting can be provided through evaluating the lsp-register-custom-settings function in a .dir-locals.el file in the root of your workspace.

((rst-mode
  . ((eval . (lsp-register-custom-settings
              '(("esbonio.logging.level" "debug")
                ("esbonio.logging.stderr" nil t)  ; Boolean values require the extra `t` indicating that they are booleans.
                ("esbonio.logging.filepath" "esbonio.log")))))))