Esbonio

2.0.0 verified Mon Apr 27 auth: no python

A language server for Sphinx and docutils-based documentation projects. Current version: 2.0.0. Release cadence: irregular, with major version bumps every few years.

pip install esbonio

Common errors

error ModuleNotFoundError: No module named 'esbonio.server' ↓

cause You are using esbonio v1.x where the module structure is different.

fix

Upgrade to esbonio 2.0+ with 'pip install --upgrade esbonio', or use 'from esbonio.lsp import EsbonioServer' for v1.x.

error AttributeError: module 'esbonio' has no attribute 'server' ↓

cause Import path is incorrect; likely trying to access server as top-level attribute.

fix

Use 'from esbonio.server import EsbonioServer' instead of 'import esbonio; esbonio.server'.

error OSError: [Errno 2] No such file or directory: 'conf.py' ↓

cause The language server is not running from a Sphinx project root.

fix

Open your Sphinx project directory in your editor, or ensure the workspace root contains conf.py.

Warnings

breaking In v2.0, the top-level module exports were reorganized. `from esbonio import X` no longer works for server-related symbols. Use `from esbonio.server import X` instead. ↓

fix Update all imports to use 'esbonio.server' submodule for server classes.

deprecated The `esbonio.lsp` module is deprecated in v2.0 and will be removed in a future version. Migrate to `esbonio.server`. ↓

fix Replace 'from esbonio.lsp import ...' with 'from esbonio.server import ...'.

gotcha Esbonio requires a Sphinx project directory to function; running outside a project root causes cryptic errors like "Unknown config". Ensure you are in a directory with conf.py. ↓

fix Run the language server from your Sphinx project root, or set the 'workspaceFolders' in LSP client.

gotcha In v2.0, the default Python requirement changed to >=3.10. Using older Python versions will cause installation failures. ↓

fix Upgrade Python to 3.10 or later, or pin esbonio to 1.x if you must use an older Python.

Install

pip install esbonio[all]

Imports

EsbonioServer

from esbonio.server import EsbonioServer

InputMessageHandler

wrong

from esbonio import InputMessageHandler

correct

from esbonio.server import InputMessageHandler

Wrong parent module, breaks in 2.0

Quickstart

Create a basic Esbonio server instance.

from esbonio.server import EsbonioServer
server = EsbonioServer()
print(server.version_info)