Changelog¶
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’salabaster
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 likereplac_self()
on custom doctree nodes. (#874)
Misc¶
v1.0.0b6 - 2024-07-19¶
Features¶
Enhancements¶
Fixes¶
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 aCompletionTrigger
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
andapp.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¶
v1.0.0b2 - 2024-04-20¶
Breaking Changes¶
Removed the
esbonio.server.logLevel
option, useesbonio.logging.level
instead.Removed the
esbonio.server.logFilter
option, it has been made obselete by the otheresbonio.logging.*
options
(#748)
Enhancements¶
Added the following configuration options
esbonio.logging.level
, set the default logging level of the serveresbonio.logging.format
, set the default format of server log messagesesbonio.logging.filepath
, enable logging to a fileesbonio.logging.stderr
, print log messages to stderresbonio.logging.window
, send log messages aswindow/logMessage
notificationsesbonio.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
andsphinx/clientDestroyed
notifications that correspond to the lifecycle of the underlying Sphinx process (#756)
Fixes¶
v1.0.0b1 - 2024-01-15¶
Breaking Changes¶
Features¶
The language server now supports reading configuration values from
workspace/configuration
requests andpyproject.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
andworkspace/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 setinitializationOptions
tonull
(#586)
Misc¶
Replace
appdirs
withplatformdirs
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 ownsource-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 thetextEdit
field of aCompletionItem
.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 theinsertText
field of aCompletionItem
which should work better with editors that do no supporttextEdits
.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 supportinsert
. (#471)
Documentation¶
Add getting started guide for Sublime Text by @vkhitrin (#522)
API Changes¶
CompletionContext
objects now expose aconfig
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 withattrs
andcattrs
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 toTrue
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 toTrue
, 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 newesbonio.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’sinitialize
request. (#497)The default
suggest_options
implementation forDirectiveLanguageFeatures
should now be more useful in that it will return the keys from a directive’soption_spec
(#498)The language server now recognises and returns
DocumentLinks
forimage::
andfigure::
directives that usehttp://
orhttps://
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
duringtextDocument/documentLink
ortextDocument/definition
requests are now caught and no longer result in frustrating error banners in clients.The
textDocument/documentLink
handler forimage::
andfigure::
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 methodscomplete_targets
called when generating role target completion itemsfind_target_definitions
used to implement goto definition for role targetsget_implementation
used to get the implementation of a role given its nameindex_roles
used to tell the language server which roles existresolve_target_link
used to implement document links for role targetssuggest_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 theRstLanguageServer
to enable adding diagnostics to a document incrementally. (#443)The
Directives
language feature can now be extended by registeringDirectiveLanguageFeatures
using the newadd_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 implementationssuggest_directives
: used to determine which directive names can be suggested in the current completion context (function
vspy:function
vsc:function
etc.)get_implementation
: used to go from a directive name (function
vspy:function
) to its implementationsuggest_options
: used to determine which directive options can be suggested in the current completion context (#453)
Deprecated¶
ArgumentCompletion
,ArgumentDefinition
andArgumentLink
directive providers have been deprecated in favour ofDirectiveLanguageFeatures
and will be removed inv1.0
(#444)Calling the
get_directives()
method on theRstLanguageServer
andSphinxLanguageServer
objects is deprecated in favour of calling theget_directives()
method on theDirectives
language feature. It will be removed inv1.0
Calling the
get_directive_options()
method on theRstLanguageServer
andSphinxLanguageServer
objects deprecated and will be removed inv1.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¶
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¶
v0.13.1 - 2022-06-29¶
Fixes¶
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 theRoles
feature. (#410)
Deprecated¶
Calling
rst.get_feature
with a string will become an error inv.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. Thesphinx.*
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 convertsphinx-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
toRstLanguageServer
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 to1
in line withsphinx-build
defaults. (#374)
v0.11.2 - 2022-05-09¶
Enhancements¶
Add
esbonio.lsp.rst._record
andesbonio.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 totrue
(#358)Language clients can now control the number of parallel jobs by providing a
sphinx.numJobs
initialization option, which defaults toauto
. Clients can disable parallel builds by setting this option to1
(#359)
Fixes¶
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 thebreathe
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
andsrcDir
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’sconfDir
,srcDir
andbuilDir
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¶
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
tov0.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 parametersesbonio.sphinx.buildDir
,esbonio.server.logFilter
,esbonio.logLevel
andesbonio.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 theinitialize
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 theconsole_scripts
entry point, so it’s now possible to launch the language server by callingesbonio
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
andliteralinclude
directives as well as thedownload
role. (#34)Language clients can now override the default
conf.py
discovery mechanism by providing aesbonio.sphinx.confDir
config option. (#62)Language clients can now override the assumption that Sphinx’s
srcdir
is the same as itsconfdir
by providing aesbonio.sphinx.srcDir
config option. (#142)
Fixes¶
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¶
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¶
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
orsite-packages
directory (#61)
v0.2.1 - 2020-12-08¶
Fixes¶
Directives that are part of the
std
orpy
Sphinx domains will now be included in completion suggestions (#31)
v0.2.0 - 2020-12-06¶
Features¶
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 ofpandoc
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
androles
(#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)