Changelog¶

v2.0.0 - 2026-04-11¶

Breaking Changes¶

Drop support for Sphinx v6. (#1086)
The default values for the following configuration options have been changed.
- esbonio.logging.level now defaults to info
- esbonio.server.completion.preferredInsertBehavior now defaults to insert
(#1094)
The default values for the following configuration options have been changed.
- esbonio.logging.format now defaults to [%(method)s(%(msgid)s)][%(name)s] %(message)s
Only log messages associated with the LSP methods initialize, initialized, textDocument/didOpen and workspace/didChangeConfiguration are shown by default, regardless of logging level.

(#1095)
The esbonio command no longer starts the server, instead the server is launched by running esbonio server, or by invoking the python -m esbonio.server (#1098)

Features¶

Add support for Sphinx v9 by @gastmaier (#1085)
Introduce the esbonio.logging.enabledMethods option which can be used to override the list of LSP methods for which log messages are shown. (#1095)

Enhancements¶

The esbonio.sphinx.pythonCommand can now be set to a single string, useful when working with virtual environments by @gastmaier (#1085)

v1.1.0 - 2026-02-19¶

Enhancements¶

Introduce esbonio.sphinx.buildArguments as an alternative name for the esbonio.sphinx.buildCommand config option.

When options like esbonio.sphinx.pythonCommand exist, esbonio.sphinx.buildCommand suggests this can be an arbitrary command which is not true and is therefore misleading. Both names will be available for the foreseable future, but esbonio.sphinx.buildArguments will be preferred and highlighted in documentation moving forward. (#1052)
The sphinx/clientCreated notification now reports the PID of the sphinx process.

The sphinx/appCreated notification now reports the Python version. (#1075)

Fixes¶

Fix the application of unsaved changes to Sphinx projects when the build is runnning on a symlinked directory by @JoHoenk (#1079)

Docs¶

Add page on Esbonio’s versioning scheme and supported Python and Sphinx versions. (#1052)
Document sphinx project discovery. (#1056)
Document default sphinx-build argument selection (part of project discovery). (#1057)
Document edge case when using the advanced form of esbonio.sphinx.pythonCommand together with the VSCode extension (or any client that provides a fallback configuration via initializationOptions). (#1074)

v1.0.0 - 2025-10-28¶

Enhancements¶

Add the esbonio.sphinx.pythonCommand.env option which can be used to set/override envrionment variables for the Sphinx process (#469)
esbonio.sphinx.pythonCommand is now an object with with following fields
- [esbonio.sphinx.pythonCommand.]command: This list of strings from the original esbonio.sphinx.pythonCommand.
- [esbonio.sphinx.pythonCommand.]env: A dictionary allowing you to add/override environment variables passed to the sphinx process
- [esbonio.sphinx.pythonCommand.]cwd: A string allowing you to change the directory in which the sphinx process is launched.
95% of the time, the previous simple list of strings was sufficient to configure the process. So the server will still accept a list of strings for esbonio.sphinx.pythonCommand and it will be automatically converted to the new object representation.

The server now treats initializationOptions as the lowest priority settings source, allowing clients to use them to provide fallback options.

(#1024)
If there is no pythonCommand configured, esbonio will now attempt to use the server’s runtime environment as a fallback. (#1027)

Fixes¶

Passing the -C flag to esbonio.sphinx.buildCommand now works as expected (#997)

Docs¶

Add guide on using the -C flag to sphinx-build to allow the use of esbonio with files that aren’t in a Sphinx project. (#997)

Misc¶

The following options have been removed
- esbonio.sphinx.envPassthrough: For ages now, the language server passes through all environment variables to the sphinx process so this option has no use.
- esbonio.sphinx.pythonPath: The original intent behind this option was to allow you to override the version of the sphinx agent. However, the better way to do this is just use a different version of esbonio.
- esbonio.sphinx.cwd: Use esbonio.sphinx.pythonCommand.cwd
- esbonio.sphinx.fallbackEnv: This was a hack to allow the VSCode extension to provide a default environment in the absence of any user configuration, client’s should set esbonio.sphinx.pythonCommand in their initializationOptions.
(#1024)
Drop Python 3.9 support (#1032)

v1.0.0b12 - 2025-07-03¶

Features¶

Re-implement support for hover requests, where the hover reveals the documentation behind cross-references like :class:`HoverContext` (#1008)

Fixes¶

Rather than trying to generate unique urls across projects (which broke many links), the preview server now sets the Cache-Control header in an attempt to ensure the preview always updates correctly. (#951, #987)
The sphinx agent no longer crashes when saving a configuration value that is a list containing exactly three items (#969)
Improve diagnostic experience in editors like neovim which do not support workspace/diagnostic/refresh requests (#998)

Misc¶

Update to pygls v2.0.0a4

Add support for Python 3.14 (#1007)

v1.0.0b11 - 2025-04-02¶

Features¶

Re-implement textDocument/definition support (#978)

Enhancements¶

Introduce esbonio.preview.synchronizeScroll setting (#979)

Fixes¶

The webview should now automatically reconnect with the server when the connection is lost. (#646)
Previews should no longer fail to update when switching between projects that produce identical output filenames (#951)
Fix ${defaultBuildDir} expansion for recent Sphinx versions (#970)

v1.0.0b10 - 2025-02-08¶

Features¶

textDocument/documentLink requests are once again supported for the following roles are directives
- .. image::
- .. figure::
- .. include::
- .. literainclude::
- :download:
- :doc:
- All :external:* roles (i.e. intersphinx references)
Both reStructuredText and MyST syntax is supported.

(#956)

Enhancements¶

Filepath completion suggestions are now provided for the :download: role (#956)

Fixes¶

The preview should no longer lose its scroll state when reloading a page that was opened at a specific anchor tag (e.g. #heading-name) (#788)
The server should now ensure that all window/workDoneProgress tokens are cleaned up (#802)
The configuration system should now produce a lot less log noise (#904)
The sphinx agent will now directly inject the webview.js script into the page alongside the line number markers. This means features like synchronised scrolling should continue to work, even if the current theme ignores the JS files provided by Sphinx. (#942)
When expanding the ${venv} config variable, the server should no longer accidentally follow symlinks back to the base Python installation (#945)

v1.0.0b9 - 2025-01-14¶

Features¶

The language server once again offers completion suggestions for arguments to the following classes of directives code-blocks, images and includes (#941)

Enhancements¶

Add support for ${venv:<path>} config variable to esbonio.sphinx.pythonCommand (#914)
Add esbonio.sphinx.buildTriggers option that gives the user control over when esbonio will rebuild the documentation (#935)

Fixes¶

Fix handling of binary websocket messages in documentation previews (#665)
The language server no longer escapes . characters in filepaths when expanding the ${defaultBuildDir} variable resulting in weird filepaths (#918)
The sphinx agent should now be able to collect diagnostics from extensions that make use of the build-finished event e.g. sphinx-needs by @AlexanderLanin (#925)
The preview no longer synchronises its scroll state when reloading the page. This should fix the issue where you would freqently lose your editor position while typing! (#933)

v1.0.0b8 - 2024-10-20¶

Enhancements¶

When clicking on internal links of a previewed page, the corresponding source file will be automatically opened in the editor (#704)
The language server should now also work with an incomplete Python environment. If one or more Sphinx extensions are missing, esbonio will still be able to run a build and report the missing extensions as a diagnostic (#913)
When asking for a html_theme that is not available in the current environment, the server will now fallback to Sphinx’s alabaster theme and report the error as a diagnostic (#916)

Fixes¶

The esbonio.preview.showLineMarkers option should now work again.

When clicking on internal links of a previewed page, the websocket connection to the language server is now preserved. (#906)
Esbonio should once again be able to parse sphinx-build command line arguments for versions of Sphinx >=8.1 (#912)

v1.0.0b7 - 2024-09-22¶

Enhancements¶

Re-implemented the esbonio.sphinx.configOverrides option (#785)

Fixes¶

Esbonio’s preview generation should no longer conflict with extensions like ablog which call methods like replac_self() on custom doctree nodes. (#874)

Misc¶

Drop support for Python 3.8 (#858)
Add support for Python 3.13 (#859)
Drop Sphinx 5.x support, add Sphinx 8.x support (#866)
Migrate to pygls v2 (#882)

v1.0.0b6 - 2024-07-19¶

Features¶

The language server now generates completions for :external: roles and their corresponding targets (#464)
Add a esbonio.sphinx.restart command which, as the name suggests, allows a client to restart one or more Sphinx processes managed by the server (#854)

Enhancements¶

Synchronised scrolling now works with files that have been .. included::, as well as autodoc docstrings (#784)
The resolution of sync scrolling has been improved with the webview also better handling the case where the requested line does not exactly match a known source location (#786)

Fixes¶

esbonio.sphinx.buildCommand settings provided in a pyproject.toml file are now resolved relative to the file’s location (#711)
The sphinx agent should no longer crash when encountering unexpected config values (#843)

v1.0.0b5 - 2024-06-07¶

Misc¶

Fix release pipeline (#831)

v1.0.0b4 - 2024-06-07¶

Features¶

Implement role target completions for MyST syntax (#823)

Enhancements¶

The server now includes the eval-rst directive in its completion suggestions for MyST files (#799)

API Changes¶

In the server’s context LanguageFeatures can now define a CompletionTrigger which among other things, allows them to declare trigger characters (#413)
In the Sphinx process, it is now possible for extensions to declare a role target provider through the app.esbonio.create_role_target_provider and app.esbonio.add_role methods. Note: This does require an associated implementation of the target provider on the server side. (#823)

Fixes¶

The language server should now launch the correct version of the sphinx agent, even if an installation of esbonio exists in the target environment (#782)
The server no longer raises ValueErrors when typing : characters in markdown files. (#800)
The server should no longer throw path mount errors when used across partitions on Windows (#810)

v1.0.0b3 - 2024-04-28¶

Features¶

Add support for role completions in MyST documents (#775)

Enhancements¶

If the client supports it, the server will now send window/showDocument requests when previewing a file.

The server will automatically react to changes to esbonio.preview.* configuration options. (#793)

Fixes¶

The server should once again, correctly guess a reasonable basic sphinx-build build command for projects located in a sub-folder of the workspace (#779)
The server should once again automatically trigger a build when previewing a file, when necessary (#783)

v1.0.0b2 - 2024-04-20¶

Breaking Changes¶

- Removed the esbonio.server.logLevel option, use esbonio.logging.level instead.
- Removed the esbonio.server.logFilter option, it has been made obselete by the other esbonio.logging.* options
(#748)

Enhancements¶

Added the following configuration options
- esbonio.logging.level, set the default logging level of the server
- esbonio.logging.format, set the default format of server log messages
- esbonio.logging.filepath, enable logging to a file
- esbonio.logging.stderr, print log messages to stderr
- esbonio.logging.window, send log messages as window/logMessage notifications
- esbonio.logging.config, override logging configuration for individual loggers, see the documentation for details
(#748)
The server will now automatically restart the underlying Sphinx process when it detects a change in its configuration (#750)
The server now emits sphinx/clientCreated, sphinx/clientErrored and sphinx/clientDestroyed notifications that correspond to the lifecycle of the underlying Sphinx process (#756)

Fixes¶

The server should no longer sometimes spawn duplicated Sphinx processes (#660)
The server now respects Sphinx configuration values like suppress_warnings (#695)
The server will no longer raise a ValueError when used in a situation where there is an empty workspace (#718)

v1.0.0b1 - 2024-01-15¶

Breaking Changes¶

Removed esbonio.lsp.spelling module, though it will be available as esbonio.ext.spelling via the esbonio-extensions package. (#583)
Drop Python 3.7 support (#584)
Drop Sphinx 4.x support (#585)

Features¶

The language server now supports reading configuration values from workspace/configuration requests and pyproject.toml files. When supported by the client, the server can detect and respond to changes in (most) configuration automatically - no more manually restarting the server! (#527)
The language server now supports workspace/symbol requests (#611)
Sphinx build progress is now reported using the window/workDoneProgress/create API (#659)
For the clients that support the pull diagnostics model, the server now supports the textDocument/diagnostic and workspace/diagnostic methods. (#689)
The language server can now provide completion suggestions for MyST directives. (#706)

Enhancements¶

When providing completion suggestions for directives, esbonio now takes the .. default-domain:: directive into account (#105)

Fixes¶

Fix path separator character on Windows by @ExaneServerTeam (#719)

v0.16.2 - 2023-10-07¶

This somewhat quiet release marks the end of the 0.x series as development has now shifted to focus on what will ultimately become the 1.0 release.

In fact this release includes a sneaky preview of the 1.0 version of the server - which includes support for multi-root projects! If you are feeling adventurous and want to try it out - change the command you use to launch esbonio to python -m esbonio.server

However, to set expectations there are <em>many</em> missing features from the preview server. The only features currently available are sphinx builds, diagnostics, document symbols and live preview/sync scrolling - but they should all work across multiple roots/projects!

See this issue for more information and if you want to submit any feedback and keep an eye out for some beta releases in the not-to-distant-future!

Enhancements¶

When creating a Sphinx application instance, the language server will now look in all workspace folders choosing the first valid configuration it finds. Failing that it will revert to its original behavior of looking in the workspaceRoot given by the client. (#467)

Fixes¶

The server will no longer fail to handle the initialize request when clients set initializationOptions to null (#586)

Misc¶

Replace appdirs with platformdirs by @coloursofnoise (#621)

v0.16.1 - 2023-02-18¶

Fixes¶

With live previews enabled, esbonio should no longer conflict with Sphinx extensions that register their own source-read handlers. (#539)

v0.16.0 - 2023-02-04¶

Features¶

Add new server.completion.preferredInsertBehavior option. This allows the user to indicate to the server how they would prefer completions to behave when accepted.

The default value is replace and corresponds to the server’s current behavior where completions replace existing text. In this mode the server will set the textEdit field of a CompletionItem.

This release also introduces a new mode insert, where completions will append to existing text rather than replacing it. This also means that 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.

Note: This option is only a hint and the server will not ensure that it is followed, though it is planned for all first party completion suggestions to (eventually) respect this setting. As of this release, all completion suggestions support replace and role, directive and directive option completions support insert. (#471)

Documentation¶

Add getting started guide for Sublime Text by @vkhitrin (#522)

API Changes¶

CompletionContext objects now expose a config field that contains any user supplied configuration values affecting completions. (#531)

Misc¶

Drop Python 3.6 support (#400)
Migrate to pygls v1.0

There are some breaking changes, but only if you use Esbonio’s extension APIs, if you simply use the language server in your favourite editor you shouldn’t notice a difference.

The most notable change is the replacement of pydantic type definitions with attrs and cattrs via the new lsprotocol package. For more details see pygls’ migration guide. (#484)
Drop support for Sphinx 3.x

Add support for Sphinx 6.x (#523)

v0.15.0 - 2022-12-03¶

Features¶

Add initial support for synced scrolling and live previews of HTML builds. Note Both of these features rely on additional integrations outside of the LSP protocol therefore requiring dedicated support from clients.

Synced scrolling support can be enabled by setting the server.enableScrollSync initialization option to True and works by injecting line numbers into the generated HTML which a client can use to align the preview window to the source window.

Live preview support can be enabled by setting the server.enableLivePreview initialization option to True, the language server will then pass the contents of unsaved files for Sphinx to build. Currently clients are responsible for triggering intermediate builds with the new esbonio.server.build command, though this requirement may be removed in future. (#490)

Enhancements¶

Completion suggestions will now also be generated for the long form (:py:func:) of roles and directives in the primary and standard Sphinx domains. (#416)
The language server should now populate the serverInfo fields of its response to a client’s initialize request. (#497)
The default suggest_options implementation for DirectiveLanguageFeatures should now be more useful in that it will return the keys from a directive’s option_spec (#498)
The language server now recognises and returns DocumentLinks for image:: and figure:: directives that use http:// or https:// references for images. (#506)

Fixes¶

Fix handling of deprecation warnings in Python 3.11 (#494)
The language server should now correctly handle errors that occur while generating completion suggestions for a directive’s options

The language server should now show hovers for directives in the primary domain. (#498)
Errors thrown by DirectiveLanguageFeatures during textDocument/documentLink or textDocument/definition requests are now caught and no longer result in frustrating error banners in clients.

The textDocument/documentLink handler for image:: and figure:: should no longer throw exceptions for invalid paths on Windows. (#506)

API Changes¶

RoleLanguageFeatures have been introduced as the preferred method of extending role support going forward. Subclasses can be implement any of the following methods
- complete_targets called when generating role target completion items
- find_target_definitions used to implement goto definition for role targets
- get_implementation used to get the implementation of a role given its name
- index_roles used to tell the language server which roles exist
- resolve_target_link used to implement document links for role targets
- suggest_roles called when generating role completion suggestions
and are registered using the new Roles.add_feature() method. (#495)

Deprecated¶

The following protocols have been deprecated and will be removed in v1.0
- TargetDefinition
- TargetCompletion
- TargetLink
The following methods have been deprecated and will be removed in v1.0
- Roles.add_target_definition_provider
- Roles.add_target_link_provider
- Roles.add_target_completion_provider
- RstLanguageServer.get_roles()
- SphinxLanguageServer.get_domain()
- SphinxLanguageServer.get_domains()
- SphinxLanguageServer.get_roles()
- SphinxLanguageServer.get_role_target_types()
- SphinxLanguageServer.get_role_targets()
- SphinxLanguageServer.get_intersphinx_targets()
- SphinxLanguageServer.has_intersphinx_targets()
- SphinxLanguageServer.get_intersphinx_projects() (#495)

v0.14.3 - 2022-11-05¶

Misc¶

Fix broken release pipeline (#480)

v0.14.2 - 2022-11-05¶

Enhancements¶

Add esbonio.server.showDeprecationWarnings option.

This is flag is primarily aimed at developers working either directly on esbonio, or one of its extensions. When enabled, any warnings (such as DeprecationWarnings) will be logged and published to the client as diagnostics. (#443)

Fixes¶

Spinx log messages are no longer duplicated after refreshing the application instance (#460)

API Changes¶

Added add_diagnostics method to the RstLanguageServer to enable adding diagnostics to a document incrementally. (#443)
The Directives language feature can now be extended by registering DirectiveLanguageFeatures using the new add_feature method. This is now the preferred extension mechanism and should be used by all extensions going forward. (#444)
DirectiveLanguageFeatures can now implement the following methods.
- index_directives: used to discover available directive implementations
- suggest_directives: used to determine which directive names can be suggested in the current completion context (function vs py:function vs c:function etc.)
- get_implementation: used to go from a directive name (function vs py:function) to its implementation
- suggest_options: used to determine which directive options can be suggested in the current completion context (#453)

Deprecated¶

ArgumentCompletion, ArgumentDefinition and ArgumentLink directive providers have been deprecated in favour of DirectiveLanguageFeatures and will be removed in v1.0 (#444)
Calling the get_directives() method on the RstLanguageServer and SphinxLanguageServer objects is deprecated in favour of calling the get_directives() method on the Directives language feature. It will be removed in v1.0

Calling the get_directive_options() method on the RstLanguageServer and SphinxLanguageServer objects deprecated and will be removed in v1.0. (#453)

Misc¶

Add Python 3.11 support (#470)

v0.14.1 - 2022-09-11¶

Fixes¶

textDocument/documentSymbol requests should no longer fail on substitution definitions. (#448)

v0.14.0 - 2022-07-31¶

Features¶

The language server now supports textDocument/implementation requests for roles and directives. (#431)

Enhancements¶

Line numbers for diagnostics for issues found within Python docstrings should now be more accurate. (#433)
Document symbol requests made for unsaved files now use the language client’s version rather than the version on disk. (#434)

Fixes¶

Diagnostics for issues found in .. included:: files should now have the correct filepath. (#425)
Extensions defined within Sphinx extensions or conf.py files can now take advantage of dependency injection (#428)
The server should now handle document symbol requests for files that are treated as reStructuredText files by a language client but don’t have an *.rst extension. (#434)

API Changes¶

It is now possible to manually load an extension by calling the load_extension method on a language server object. (#429)
LanguageFeatures can now respond to textDocument/implementation requests by providing an implementation method and a collection of implementation_triggers. (#431)

v0.13.1 - 2022-06-29¶

Fixes¶

Log messages from Sphinx’s startup are now captured and forwarded onto the language client. (#408)
Log messages from the server’s startup are now captured and forwarded onto the language client. (#417)
Fixed handling of default roles when getting a document’s initial doctree. (#418)

API Changes¶

Improved type annotations allow rst.get_feature to be called with a language feature’s type and have the return type match accordingly. This should allow editors to provide better autocomplete suggestions etc. (#409)
esbonio_setup functions can now request specific language features and servers, just by providing type annotations e.g:
```
from esbonio.lsp.roles import Roles
from esbonio.lsp.sphinx import SphinxLanguageServer

def esbonio_setup(rst: SphinxLanguageServer, roles: Roles):
    ...
```
This function will then only be called when the language server is actually an instance of SphinxLanguageServer and only when that lanuage server instance contains an intance of the Roles feature. (#410)

Deprecated¶

Calling rst.get_feature with a string will become an error in v.1.0, a language feature’s class should be given instead. (#409)

v0.13.0 - 2022-05-27¶

Features¶

Add initial textDocument/hover support, with documentation for roles and directives being shown.

Add > to completion triggers. (#311)

Fixes¶

The language server now correctly handles diagnosics originating from .. c:function:: directives. (#393)

v0.12.0 - 2022-05-22¶

Features¶

The language server now supports many (but not all) sphinx-build command line options. The sphinx.* section of the server’s initialization options has been extened to include the following options.
- configOverrides
- doctreeDir
- keepGoing
- makeMode
- quiet
- silent
- tags
- verbosity
- warningIsError
See the documentation for details.

Additionally, a new cli application esbonio-sphinx is now available which language clients (or users) can use to convert sphinx-build cli options to/from the server’s initialization options. (#360)

Enhancements¶

textDocument/documentSymbol responses now include symbol information on directives. (#374)

Fixes¶

.. include:: directives no longer break goto definition for :ref: role targets (#361)

API Changes¶

Add method get_initial_doctree to RstLanguageServer which can be used to obtain a doctree of the given file before any role and directives have been applied. (#374)

Misc¶

The esbonio.sphinx.numJobs configuration now defaults to 1 in line with sphinx-build defaults. (#374)

v0.11.2 - 2022-05-09¶

Enhancements¶

Add esbonio.lsp.rst._record and esbonio.lsp.sphinx._record startup modules. These can be used to record all LSP client-sever communication to a text file. (#380)

Fixes¶

The language server now detects functionality bundled with standard Sphinx extensions (#381)

v0.11.1 - 2022-04-26¶

Fixes¶

textDocument/documentLink requests no longer fail when encountering :: characters in C++ references. (#377)

v0.11.0 - 2022-04-18¶

Features¶

Add textDocument/documentLink support.

The server supports resolving links for role targets with initial support for intersphinx references and local :doc: references.

The server also supports resolving links for directive arguments with initial support for .. image::, .. figure::, .. include:: and .. literalinclude:: directives. (#294)

Enhancements¶

Language clients can now control if the server forces a full build of a Sphinx project on startup by providing a sphinx.forceFullBuild initialization option, which defaults to true (#358)
Language clients can now control the number of parallel jobs by providing a sphinx.numJobs initialization option, which defaults to auto. Clients can disable parallel builds by setting this option to 1 (#359)

Fixes¶

Goto definition for :ref: targets now works for labels containing - characters (#357)
Goto definition for :doc: targets will now only return a result if the referenced document actually exists. (#369)

v0.10.3 - 2022-04-07¶

Fixes¶

A client’s capabilities is now respected when constructing CompletionItems (#270)
Instead of spamming the client with notifications, the language server now reports Sphinx config/build errors as diagnostics. (#315)
Previews should now work on MacOS (#341)
Running $ esbonio directly on the command line now correctly starts the server again (#346)
The language server should no longer fail when suggesting completions for directives that are not class based. e.g. DirectiveContainer based directives from the breathe extension. (#353)

v0.10.2 - 2022-03-22¶

Fixes¶

Previews on Windows should now start correctly (#341)

v0.10.1 - 2022-03-20¶

Fixes¶

The language server should now correctly handle buildDir, confDir and srcDir config values containing paths relative to ~ (#342)

v0.10.0 - 2022-03-17¶

Features¶

The server now provides an esbonio.server.preview command that can be used to preview HTML Sphinx projects via a local HTTP server. (#275)
The language server now accepts paths relative to ${workspaceFolder} for Sphinx’s confDir, srcDir and builDir options. (#304)
The language server now supports textDocument/definition requests for .. image:: directive arguments. (#318)
The language server now supports textDocument/definition requests for .. figure:: directive arguments. (#319)
The language server will now look in sphinx extension modules and conf.py files for extensions to the language server. (#331)

Fixes¶

The language server no longer crashes when asked to --exclude a module that would not be loaded anyway. (#313)
Completion suggestions for domain objects referenced by roles such as :doc:, :ref:, :func: and many more now correctly update each time a rebuild is triggered. (#317)
Goto definition on a directive’s arguments is no longer foiled by trailing whitespace. (#327)

v0.9.0 - 2022-03-07¶

Features¶

The language server now supports providing documentation on roles, directives (and their options). Note however, this requires the relevant documentation to be explicitly added to the relevant LanguageFeatures. (#36)
The server now listens for workspace/didDeleteFiles notifications. (#93)
Add experimental spell checking support. (#271)
The language server now provides completion suggestions for .. code-block:: and .. highlight:: language names. (#273)
The language server now supports completionItem/resolve requests, it is currently implemented for roles, directives and directive options. (#274)
The language server now supports textDocument/definition requests for .. include:: directive arguments. (#276)
The language server now supports textDocument/definition requests for .. literalinclude:: directive arguments. (#277)

Fixes¶

Diagnostics are now cleared for deleted files. (#291)

v0.8.0 - 2021-11-26¶

Features¶

The language server now respects the project’s default_role setting. (#72)
Initial implementation of the textDocument/documentSymbols request which for example, powers the “Outline” view in VSCode. Currently only section headers are returned. (#242)
The esbonio.sphinx.buildDir option now supports ${workspaceRoot} and ${confDir} variable expansions (#259)

Fixes¶

Role target CompletionItems now preserve additional cross reference modifiers like ! and ~ (#211)
Intersphinx projects are now only suggested if they contain targets relevant to the current role. (#244)
Variables are now properly substituted in diagnostic messages. (#246)

v0.7.0 - 2021-09-13¶

Features¶

Add initial goto definition support. Currently only support definitions for :ref: and :doc: role targets. (#209)

Fixes¶

Completion suggestions for :option: targets now insert text in the correct format (<progname> <option>) (#212)
Diagnostics are now correctly cleared on Windows (#213)
Completion suggestions are no longer given in the middle of Python code. (#215)
CompletionItems should no longer corrupt existing text when selected. (#223)

Misc¶

Updated pygls to v0.11.0 (#218)

v0.6.2 - 2021-06-05¶

Fixes¶

The language server now correctly handles windows file URIs when determining Sphinx’s build directory. (#184)
Role and role target completions are now correctly generated when the role is being typed within parenthesis e.g. (:kbd:... (#191)
Path variables like ${confDir} and ${workspaceRoot} are now properly expanded even when there are no additional path elements. (#208)

Misc¶

The cli arguments --cache-dir, --log-filter, --log-level and --hide-sphinx-output have been replaced with the configuration parameters esbonio.sphinx.buildDir, esbonio.server.logFilter, esbonio.logLevel and esbonio.server.hideSphinxOutput respectively (#185)
The language server’s startup sequence has been reworked. Language clients are now required to provide configuration parameters under the initializationOptions field in the initialize request. (#192)
The language server will now send an esbonio/buildComplete notification to clients when it has finished (re)building the docs. (#193)
An entry for esbonio has been added to the console_scripts entry point, so it’s now possible to launch the language server by calling esbonio directly (#195)

v0.6.1 - 2021-05-13¶

Fixes¶

Intersphinx projects are now only included as completion suggestions for roles which target object types in a project’s inventory. (#158)
Fix the uri representation of Windows paths when reporting diagnostics (#166)
The language server now attempts to recreate the Sphinx application if the user updates a broken conf.py. (#169)
The language server no longer crashes if clients don’t send the esbonio.sphinx configuration object (#171)
Docstrings from Sphinx and Docutils’ base directive classes are no longer included in completion suggestions as they are not useful. (#178)
Sphinx build time exceptions are now caught and reported (#179)
Fix Method not found: $/setTrace exceptions when running against VSCode (#180)

v0.6.0 - 2021-05-07¶

Features¶

The Language Server will now offer filepath completions for the image, figure, include and literalinclude directives as well as the download role. (#34)
Language clients can now override the default conf.py discovery mechanism by providing a esbonio.sphinx.confDir config option. (#62)
Language clients can now override the assumption that Sphinx’s srcdir is the same as its confdir by providing a esbonio.sphinx.srcDir config option. (#142)

Fixes¶

The Language Server no longer throws an exception while handling errors raised during initialization of a Sphinx application. (#139)
The Language Server now correctly offers completions for autoxxx directive options (#100)

Misc¶

Upgrage pygls to v0.10.x (#144)

v0.5.1 - 2021-04-20¶

Fixes¶

Pin pygls<0.10.0 to ensure installs pick up a compatible version (#147)

v0.5.0 - 2021-02-25¶

Features¶

The language server now reports invalid references as diagnostics (#57)
Add --log-level cli argument that allows Language Clients to control the verbosity of the Language Server’s log output. (#87)
Directive completions are now domain aware. (#101)
Role and role target completions are now domain aware. (#104)
Intersphinx completions are now domain aware (#106)
Add log-filter cli argument that allows Language Clients to choose which loggers they want to recieve messages from. Also add --hide-sphinx-output cli argument that can suppress Sphinx’s build log as it it handled separately. (#113)
Add -p, --port cli arguments that start the Language Server in TCP mode while specifying the port number to listen on. (#114)
Add --cache-dir cli argument that allows Language Clients to specify where cached data should be stored e.g. Sphinx’s build output. (#115)

Fixes¶

The language server now reloads when the project’s conf.py is modified (#83)
$/setTraceNotification notifications from VSCode no longer cause exceptions to be thrown in the Language Server. (#91)
Consistency errors are now included in reported diagnostics. (#94)
Ensure :doc: completions are specified relative to the project root. (#102)

v0.4.0 - 2021-02-01¶

Features¶

Directive option completions are now provided within a directive’s options block (#36)
For projects that use interpshinx completions for intersphinx targets are now suggested when available (#74)

Fixes¶

Regex that catches diagnostics from Sphinx’s output can now handle windows paths. Diagnostic reporting now sends a proper URI (#66)
Diagnostics are now reported on first startup (#68)
Fix exception that was thrown when trying to find completions for an unknown role type (#73)
The server will not offer completion suggestions outside of a role target (#77)

v0.3.0 - 2021-01-27¶

Features¶

Errors in Sphinx’s build output are now parsed and published to the LSP client as diagnostics (#35)
Directive completions now include a snippet that prompts for any required arguments (#58)

Fixes¶

Errors encountered when initialising Sphinx are now caught and the language client is notified of an issue. (#33)
Fix issue where some malformed CompletionItem objects were preventing completion suggestions from being shown. (#54)
Windows paths are now handled correctly (#60)
Server no longer chooses conf.py files that are located under a .tox or site-packages directory (#61)

v0.2.1 - 2020-12-08¶

Fixes¶

Directives that are part of the std or py Sphinx domains will now be included in completion suggestions (#31)

v0.2.0 - 2020-12-06¶

Features¶

Python log events can now published to Language Clients (#27)
Sphinx’s build output is now redirected to the LSP client as log messages. (#28)
Suggest completions for targets for a number of roles from the std and py domains including ref, doc, func, meth, class and more. (#29)

Fixes¶

Fix discovery of roles so that roles in Sphinx domains are used and that unimplemented docutils roles are not surfaced. (#26)

v0.1.2 - 2020-12-01¶

Misc¶

Use ubuntu-20.04 for Python builds so that the correct version of pandoc is available (#25)

v0.1.1 - 2020-12-01¶

Misc¶

Ensure pandoc is installed to fix the Python release builds (#24)

v0.1.0 - 2020-12-01¶

Features¶

The language server can now offer completion suggestions for directives and roles (#23)

0.0.6 - 2020-11-21¶

Misc¶

Add --version option to the cli that will print the version number and exit. (#11)

0.0.5 - 2020-11-20¶

Misc¶

Update build pipeline to use towncrier to autogenerate release notes and changelog entries (#5)