Esbonio
The Esbonio extension integrates the The What about the reStructuredText Extension?You may already be familiar with the reStructuredText extension which, as of v171.0.0 now also integrates the Wait.. so why does the Esbonio VSCode extension still exist? The reStructuredText extension takes a more conservative approach to adopting new VSCode features and APIs leaving the Esbonio extension free to more aggressively follow new developments.
The Esbonio extension is developed alongside the language server itself, which allows for easy testing of new features without waiting for downstream projects to catch up.
Finally, the Esbonio extension serves as an up to date reference for projects that integrate That sounds great... but which extension is right for me? Try the reStructuredText extension if
Try the Esbonio extension if
FeaturesPreviewThe extension can show a HTML preview of the documentation CompletionsThe language server can provide completion suggestions in various contexts Goto DefintionGoto definition is currently implemented for objects linked to by
DiagnosticsErrors from a build are published to VSCode as diagnostics OutlineSections within a document are displayed in the "Outline" view Syntax HighlightingSyntax Highlighting is provided thanks to the reStructuredText Syntax Highlighting Extension extension. SetupThe language server works by wrapping an instance of Sphinx's application object, inspecting it and exposing the results over the Language Service Protocol. As Sphinx is a Python application this also dictates thats the Language Server is written in Python and distributed as a package on PyPi. In order to correctly wrap your Sphinx application this requires the Language Server be installed into the same environment as the one that you use to build your documentation. There are a number of ways this can be accomplished. AutomaticallyThe extension does its best to automate the installation and application of updates to the
Language Server. By default Esbonio will use the Python environment you have configured
Python extension
when installing and running the server. If however, you don't have the Python extension
installed or you want to use a different Python environment for your documentation there
is a configuration option There are a number of configuration options that allow you to control exactly how installation and updates are handled. See the documentation for more details. ManuallyAlternatively you can opt to manage the installation of the language server entirely yourself. To install the Lanaguage Server open the terminal in your desired Python environment and run
Then all you have to ensure is that Esbonio is configured to use the same environment,
either through the
Python extension
or through the To also manage updates manually, be sure to look at the documentation for options on how to disable automatic updates. |