Configuration¶
Esbonio provides a flexible configuration system, allowing you to adapt the server to fit your project’s needs.
Scopes & Sources¶
Configuration values are assigned one of the following scopes
global
: For options that apply to the entire language server e.g. logging level.project
: For options that apply to a single project e.g. asphinx-build
command.
The language server supports reading configuration values from the following sources.
(Priortiy) Source |
Supported Scopes |
Notes |
---|---|---|
(1) |
|
Settings for multiple projects are not supported. |
|
||
(3) |
|
When determining the value to assign to a particular configuration option, Esbonio will merge options given by the sources in order of descending priority i.e. initializationOptions
will override all other sources.
Options¶
Below are all the configuration options supported by the server and their effects.
Completion¶
The following options affect completion suggestions.
- global string esbonio.server.completion.preferredInsertBehavior¶
Controls how completions behave when accepted, the following values are supported.
replace
(default)Accepted completions will replace existing text, allowing the server to rewrite the current line in place. This allows the server to return all possible completions within the current context. In this mode the server will set the
textEdit
field of aCompletionItem
.insert
Accepted completions will append to existing text rather than replacing it. Since rewriting is not possible, only the completions that are compatible with any existing text will be returned. In this mode the server will set the
insertText
field of aCompletionItem
which should work better with editors that do no supporttextEdits
.
Developer¶
The following options are useful when extending or working on the language server
- global boolean esbonio.server.showDeprecationWarnings¶
Developer flag which, when enabled, the server will publish any deprecation warnings as diagnostics.
- global boolean esbonio.server.enableDevTools (boolean)¶
Enable lsp-devtools integration for the language server itself.
- global boolean esbonio.sphinx.enableDevTools (boolean)¶
Enable lsp-devtools integration for the Sphinx subprocess started by the language server.
- global string[] esbonio.sphinx.pythonPath (string[])¶
List of paths to use when constructing the value of
PYTHONPATH
. Used to inject the sphinx agent into the target environment.”
Logging¶
The following options control the logging output of the language server.
- global string esbonio.logging.level¶
Sets the default level of log messages emitted by the server. The following values are accepted, sorted in the order from least to most verbose.
critical
fatal
error
(default)warning
info
debug
- global string esbonio.logging.format¶
Sets the default format string to apply to log messages. This can be any valid %-style format string, referencing valid LogRecord attributes
Default value:
[%(name)s]: %(message)s
- global string esbonio.logging.filepath¶
If set, record log messages in the given filepath (relative to the server’s working directory)
- global boolean esbonio.logging.stderr¶
If
True
(the default), the server will print log messages to the process’ stderr
- global boolean esbonio.logging.window¶
If
True
, the server will send messages to the client as window/logMessage notifications
- global object esbonio.logging.config¶
This is an object used to override the default logging configuration for specific, named loggers. Keys in the object are the names of loggers to override, values are a dictionary that can contain the following fields
level
if present, overrides the value ofesbonio.logging.level
format
if present, overrides the value ofesbonio.logging.format
filepath
if present, overrides the value ofesbonio.logging.filepath
stderr
if present, overrides the value ofesbonio.logging.stderr
window
if present, overrides the value ofesbonio.logging.window
Examples¶
The following is equivalent to the server’s default logging configuration:
{
"esbonio": {
"logging": {
"level": "error",
"format": "[%(name)s]: %(message)s",
"stderr": true,
"config": {
"sphinx": {
"level": "info",
"format": "%(message)s"
}
}
}
}
}
This sets the default log level to debug
and dials back or redirects the output from some of the noisier loggers:
{
"esbonio": {
"logging": {
"level": "debug",
"config": {
"esbonio.Configuration": {
"level": "info"
},
"esbonio.PreviewServer": {
"filename": "http.log",
"stderr": false
},
"esbonio.WebviewServer": {
"level": "error"
}
}
}
}
}
Loggers¶
The following table summarises (some of) the available loggers and the type of messages they report
Name |
Description |
---|---|
|
Messages coming from |
|
Messages about merging configuration from multiple sources and notifying the rest of the server when values change. |
|
Messages from the component orchestrating the HTTP and Websocket servers that power the preview functionality |
|
Records the HTTP traffic from the server that serves the HTML files built by Sphinx |
|
Messages from the component that manages the server’s underlying Sphinx processes |
|
Messages about the websocket connection between the HTML viewer and the server |
|
Log messages coming from Python’s warnings framework |
|
Log messages coming from an underlying sphinx process |
Sphinx¶
The following options control the creation of the Sphinx application object managed by the server.
- project string[] esbonio.sphinx.buildCommand¶
The
sphinx-build
command to use when invoking the Sphinx subprocess.
- project string[] esbonio.sphinx.pythonCommand¶
The command to use when launching the Python interpreter for the process hosting the Sphinx application. Use this to select the Python environment you want to use when building your documentation.
- project string esbonio.sphinx.cwd¶
The working directory from which to launch the Sphinx process. If not set, this will default to the root of the workspace folder containing the project.
- project string[] esbonio.sphinx.envPassthrough¶
A list of environment variables to pass through to the Sphinx process.
- project object sphinx.configOverrides¶
This option can be used to override values set in the project’s
conf.py
file. This can be used to replace both thesphinx-build -D
andsphinx-build -A
cli options.For example the cli argument
-Dlanguage=cy
overrides a project’s language, the equivalent setting using theconfigOverrides
setting would be{ "sphinx.configOverrides": { "language": "cy" } }
Simiarly the argument
-Adocstitle=ProjectName
overrides the value of thedocstitle
variable inside HTML templates, the equivalent setting usingconfigOverrides
would be{ "sphinx.configOverrides": { "html_context.docstitle": "ProjectName" } }
Preview¶
The following options control the behavior of the preview
- project boolean esbonio.sphinx.enableSyncScrolling¶
Enable support for syncronsied scrolling between the editor and preview pane
Note
In order to use syncronised scrolling, dedicated support for it needs to be implemented by your language client. See lsp-feat-sync-scrolling for details.
- project string esbonio.preview.bind¶
The network interface to bind the preview server to.
- project integer esbonio.preview.httpPort¶
The port number to bind the HTTP server to. If
0
(the default), a random port number will be chosen
- project integer esbonio.preview.wsPort¶
The port number to bind the WebSocket server to. If
0
(the default), a random port number will be chosen