Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
219 lines (155 sloc) 6.9 KB

Configuration

By `Lex Li`_

This article shows how to configure the extension.

Sample Project

Before digging further into the configuration, please create a sample project first.

mkdir sphinxtest
cd sphinxtest
sphinx-quickstart
code .

The test project has the following contents, like makefile, conf.py, and build folder.

Now this project is opened in Visual Studio Code.

Important

You also need to install prerequisites. Please refer to :doc:`/articles/prerequisites` for details.

Important

If Microsoft Python extension is installed, please first open conf.py of your project. The Python extension should ask you to specify the Python build to use (in case your machine has multiple Python builds installed). Your preference is saved to .vscode/settings.json file, and is then used by this extension.

If you didn't make a choice, this extension might not be able to use the Python build you expected.

Live Preview

The keyboard shortcuts are

  • ctrl+shift+r (on Mac cmd+shift+r) Preview
  • ctrl+k ctrl+r (on Mac cmd+k cmd+r) Preview to Side

Note

To learn all keyboard shortcuts of this extension, please refer to :doc:`/articles/shortcuts`.

By triggering a preview, this extension might show a list of options,

_static/selection.png

Once an option is chosen, this extension is going to render the preview page accordingly.

A status bar item is also added,

_static/reset.png

By clicking this item, the selected option is reset, and the option list is displayed once again.

You might tune the following three settings when the extension cannot locate the generated HTML pages.

First, a new file .vscode/settings.json needs to be created under the root directory shown in your Explorer tab in Visual Studio Code.

Its default content is as below,

{
    "restructuredtext.builtDocumentationPath" : "${workspaceRoot}/_build/html",
    "restructuredtext.confPath"               : "${workspaceRoot}",
    "restructuredtext.updateOnTextChanged"    : "true",
    "restructuredtext.updateDelay"            : 300,
    "restructuredtext.sphinxBuildPath"        : null
}

Note

All settings are set to the default values.

A file with customized values might look as below,

{
    "restructuredtext.builtDocumentationPath" : "${workspaceRoot}/build/html",
    "restructuredtext.confPath"               : "${workspaceRoot}/source",
    "restructuredtext.updateOnTextChanged"    : "false",
    "restructuredtext.updateDelay"            : 1000,
    "restructuredtext.sphinxBuildPath"        : "C:\\Users\\lextm\\AppData\\Local\\Programs\\Python\\Python36\\Scripts\\sphinx-build.exe"
}

Conf.py Path

Important

For release 68.0.0 and above, this option is maintained automatically by the extension in most cases, so you don't need to modify it unless really neccessary.

The meaning of this setting also changes. Now it stores the active preview option for the workspace/folder.

  • If it is "", then docutils is used to render the preview page.
  • If it is a valid folder, then conf.py from that folder is used by Sphinx to render the preview page.
  • If it is not set, then this extension shows a list of options before generating a preview page.

It is not recommended to use docutils, as it does not work on Sphinx specific features, and the preview pages can look differently.

This extension relies on Sphinx conf.py to generate preview pages.

Usually when a Sphinx project is opened, conf.py is located at the root in Explorer folder, and that's the default value ${workspaceRoot} of restructuredtext.confPath.

If you have conf.py at another location, then restructuredtext.confPath should point to the proper path, such as ${workspaceRoot}/source.

Note

This should be an absolute path.

Important

For release 68.0.0 and above, the conf.py file must be located within the root folder.

Sphinx Build Path (25.0 and above)

The value for restructuredtext.sphinxBuildPath above depends on your Python installation.

On Windows Python can be installed to all possible locations and does not appear in PATH environment variable. Then you must set this value to the proper sphinx-build.exe file path.

Note

This should be an absolute path. If you don't set this setting, but python.pythonPath, then this extension will then pick up that setting instead. Also python.pythonPath should be an absolute path.

Linter

The linter support is based on doc8.

Linting is automatically enabled if the linter doc8 is installed. The linter scans the opened files and highlights those lines with issues detected. The PROBLEMS tab should also show all issues detected for easy navigation.

Note

A warning is displayed if doc8 cannot be found.

Executable Path

It expects doc8 Python module to be installed and already added to the path. If it is installed but cannot be found, add the path to your preferences as seen below,

{
    "restructuredtext.linter.executablePath": "PathToExecutable"
}

Note

This should be an absolute path. If you don't set this setting, but python.pythonPath, then this extension will then pick up that setting instead. Also python.pythonPath should be an absolute path.

Lint onType or onSave or not at all

By default the linter will lint on the fly but can be changed to linting as you save. Note that linting on save is most useful when auto-save is on. Use the setting below if to change the behavior with the values onType, onSave, and off,

{
    "restructuredtext.linter.run": "onType"
}

IntelliSense

This feature is disabled by default, as it is still experimental.

To enable it at directory level, a new file .vscode/settings.json needs to be created under the root directory shown in your Explorer tab in Visual Studio Code.

Its default content is as below,

{
    "restructuredtext.languageServer.disabled": true
}

To enable IntelliSense, change the value to false,

{
    "restructuredtext.languageServer.disabled": false
}

You need to restart Visual Studio Code for this change to take effect.

Note

You can also enable it at machine level, by making this change in Preferences -> Settings.

Once configured properly, suggestions would be provided when pressing / after lines such as - :doc: to help input file path much quicker.

Related Resources