Configuration

File discovery

Similar to ruff, the LSP supports hierarchical configuration, such that the “closest” config file in the directory hierarchy is used for every individual file, with all paths in the config file being resolved relative to the directory containing that config file.

Configuration can be in a sphinx.toml or pyproject.toml file, although note any pyproject.toml that lacks a [tool.sphinx] section will be ignored.

For example, given the following directory structure:

project/
├── docs1/
│   ├── conf.py
│   └── doc1.rst
│   └── sphinx.toml
├── docs2/
│   ├── conf.py
│   └── doc2.rst
└── sphinx.toml

The configuration for doc1.rst will be read from project/docs1/sphinx.toml, whereas for doc2.rst it will be read from project/sphinx.toml.

Top-level configuration

srcdir:

The path to the source directory, relative to the config file. The default is ".".

builds:

A table of build configurations. The default is a single build configuration named default.

Build configuration

outdir:

The path to the output directory, relative to the config file. The default is "_build".

confdir:

The path to the configuration directory, relative to the config file.

doctreedir:

The path to the doctree directory, relative to the config file.

command:

The command to run to build the project. The command can contain placeholders withing double curly braces, e.g. "sphinx-build {{srcdir}} {{outdir}}".

The following placeholders are supported:

srcdir:

The absolute path to the source directory.

confdir:

The absolute path to the configuration directory (empty if not set).

doctreedir:

The absolute path to the doctree directory (empty if not set).

outdir:

The absolute path to the output directory.

file:

The absolute path to a specific file to rebuild (empty if not set).

Special build names

The build name default is used as the default build configuration.

If present, the build name index is used for the build configuration by the language server, to find the index database (see How it works).

If present, the build name preview is used for the build configuration by the HTML previewer, to find the HTML files.

For example, the following configuration specifies different output directories for the server and preview builds:

srcdir = "source"

[builds.index]
outdir = "_build/index"
command = "sphinx-build -b dummy {{srcdir}} {{outdir}}"

[builds.preview]
outdir = "_build/preview"
command = "sphinx-build -b html {{srcdir}} {{outdir}}"

[tool.sphinx]
srcdir = "source"

[tool.sphinx.builds.index]
outdir = "_build/index"
command = "sphinx-build -b dummy {{srcdir}} {{outdir}}"

[tool.sphinx.builds.preview]
outdir = "_build/preview"
command = "sphinx-build -b html {{srcdir}} {{outdir}}"