VS Code Extension¶
The Sphinx Language Support extension provides features for working with Sphinx projects in Visual Studio Code.
Features¶
Sphinx builds¶
To launch a build for a source file of a Sphinx project (rst or md), you can either:
Click on the editor title icon:
Right-click in the editor and select “Launch Sphinx Build “
Right-click on a file in the Explorer panel and select “Launch Sphinx Build”
If you have multiple build configurations for your project, this will first prompt you to select the build configuration to use.
If a build configuration is found/selected (see Configuration), then the command will be launched in a Terminal.
To guard against multiple builds running at the same time, for the same output directory, terminals are re-used for the same output directory.
Note
By default, new terminals will open with the workspace folder as the working directory, and also first apply configured platform settings, such as loading the selected Python environment.
Tip
The extension does not currently handle automatically re-running the Sphinx build when the source files change.
For this you may want to check out sphinx-autobuild.
HTML Preview¶
The following commands will look for the preview or default build configuration,
to determine the relative path to the built HTML file (see Configuration).
To open a preview of the HTML output for a source file (rst or md),
you can either:
Click on the editor title icon:
Right-click in the editor and select “Open Sphinx Preview” or “Open Sphinx Preview (External)”:
Right-click on a file in the Explorer panel and select “Open Sphinx Preview” or “Open Sphinx Preview (External)”:
Selecting External will open the preview in your default browser, otherwise it will open in a new tab in the editor.
Note
This extension uses Live Preview to provide the preview. See this extension for more configuration options.
For example, you may want to increase the livePreview.previewDebounceDelay,
if working on a remote filesystem.
conf.py files¶
Configuration variables¶
For autocompletion of configuration values,
start typing at the start of a line and they should show automatically, or press Ctrl+Space.
*.rst files¶
Outline¶
For an outline of the document, open the “Outline” view in the Sidebar.
Directives¶
To autocomplete a directive, start typing at the start of a line and they should show automatically, or press Ctrl+Space.
For a description of a directive, hover over the directive name.
