Getting Started#

This section contains notes on how to use the language server with your text editor of choice.

Don’t see your favourite editor?

Feel free to submit a pull request with steps on how to get started or if you’re not sure on where to start, open an issue and we’ll help you figure it out.

Installation#

The language server can be installed using pip, or if you prefer, conda.

Sphinx and the reStructuredText format itself are highly extensible so the available features can differ greatly from project to project. For this reason the esbonio should be installed into the same environment you use when building your documentation. Otherwise the language server will fail to properly understand your project.

Configuration#

Sphinx Options#

The following options control the creation of the Sphinx application object managed by the server.

sphinx.buildDir (string)#

By default the language server will choose a cache directory (as determined by platformdirs) to place Sphinx’s build output. This option can be used to force the language server to use a location of your choosing, currently accepted values include:

  • /path/to/src/ - An absolute path

  • ${workspaceRoot}/docs/src - A path relative to the root of your workspace

  • ${workspaceFolder}/docs/src - Same as ${workspaceRoot}, placeholder for true multi-root workspace support.

  • ${confDir}/../src/ - A path relative to your project’s confDir

sphinx.builderName (string)#

By default the language server will use the html builder. This option allows you to specify the builder you wish to use.

Note

Some features (such as previews) are currently only available for the html builder.

sphinx.confDir (string)#

The language server attempts to automatically find the folder which contains your project’s conf.py. If necessary this can be used to override the default discovery mechanism and force the server to use a folder of your choosing. Currently accepted values include:

  • /path/to/docs - An absolute path

  • ${workspaceRoot}/docs - A path relative to the root of your workspace.

  • ${workspaceFolder}/docs - Same as ${workspaceRoot}, placeholder for true multi-root workspace support.

sphinx.configOverrides (object)#

This option can be used to override values set in the project’s conf.py file. This covers both the sphinx-build -D and sphinx-build -A cli options.

For example the cli argument -Dlanguage=cy overrides a project’s language, the equivalent setting using the configOverrides setting would be:

{
   "sphinx.configOverrides": {
      "language": "cy"
   }
}

Simiarly the argument -Adocstitle=ProjectName overrides the value of the docstitle variable inside HTML templates, the equivalent setting using configOverrides would be:

{
   "sphinx.configOverrides": {
      "html_context.docstitle": "ProjectName"
   }
}
sphinx.doctreeDir (string)#

This option can be used to specify the directory into which the language server will write the project’s doctree cache. Currently accepted values include:

  • /path/to/docs - An absolute path

  • ${workspaceRoot}/doctrees - A path relative to the root of your workspace.

  • ${workspaceFolder}/doctrees - Same as ${workspaceRoot}, placeholder for true multi-root workspace support.

  • ${confDir}/../doctrees - A path relative to your project’s confDir

  • ${buildDir}/.doctrees - A path relative to your project’s buildDir

sphinx.forceFullBuild (boolean)#

Flag that indicates if the server should force a full build of the documentation on startup. (Default: false)

sphinx.keepGoing (boolean)#

Continue building even when errors (from warnings) are encountered. (Default: false)

sphinx.makeMode (boolean)#

If true the language server will behave like sphinx-build when invoked with the -M argument. If false the language server will behave like sphinx-build when invoked with the -b argument. (Default: true)

sphinx.numJobs (string or integer)#

Controls the number of parallel jobs used during a Sphinx build.

The default value of "auto" will behave the same as passing -j auto to a sphinx-build command. Setting this value to 1 effectively disables parallel builds.

sphinx.quiet (boolean)#

Hides all standard Sphinx output messages. Equivalent to the sphinx-build -q cli option. (Default false)

sphinx.silent (boolean)#

Hides all Sphinx output. Equivalent to the sphinx-build -Q cli option. (Default false)

sphinx.srcDir (string)#

The language server assumes that your project’s srcDir (the folder containing your rst files) is the same as your projects’s confDir. If this assumption is not true, you can use this setting to tell the server where to look. Currently accepted values include:

  • /path/to/src/ - An absolute path

  • ${workspaceRoot}/docs/src - A path relative to the root of your workspace

  • ${workspaceFolder}/docs/src - Same as ${workspaceRoot}, placeholder for true multi-root workspace support.

  • ${confDir}/../src/ - A path relative to your project’s confDir

sphinx.tags (string[])#

A list of tags to enable. See the documentation on the sphinx-build -t cli option for more details. (Default: [])

sphinx.verbosity (integer)#

Set the verbosity level of Sphinx’s output. (Default: 0)

sphinx.warningIsError (boolean)#

Treat warnings as errors. (Default: false)

Server Options#

The following options control the behavior of the language server as a whole.

server.completion.preferredInsertBehavior (string)#

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 a CompletionItem.

  • 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 a CompletionItem which should work better with editors that do no support textEdits.

server.enableScrollSync (boolean)#

When enabled, the server will inject line numbers into HTML build output making it possible for clients to implement synced scrolling.

server.enableLivePreview (boolean)#

When enabled, the server will report diagnostics and build projects taking into account the state of unsaved files. Note: The server currently relies on the client to tell it when to build unsaved files by issuing a esbonio.server.build command.

server.logLevel (string)#

This can be used to set the level of log messages emitted by the server. This can be set to one of the following values.

  • error (default)

  • info

  • debug

server.logFilter (string[])#

The language server will typically include log output from all of its components. This option can be used to restrict the log output to be only those named.

server.hideSphinxOutput (boolean)#

Deprecated since version 0.12.0: The sphinx.quiet (boolean) and sphinx.silent (boolean) options should be used instead. This will be removed in v1.0.

Normally any build output from Sphinx will be forwarded to the client as log messages. If you prefer this flag can be used to exclude any Sphinx output from the log.

server.showDeprecationWarnings (boolean)#

Developer flag which, when enabled, the server will publish any deprecation warnings as diagnostics.

Examples#

For some editors where the setup is more manual, we do provide some example configurations to help get you started.

Debugging#

In the event that something does not work as expected, you can increase the logging level of the server by setting the server.logLevel (string) option to debug.

Commands#