reStructuredText Preview (docutils)
A live side-by-side preview for .rst files. Rendering is done by real
docutils, the reference reStructuredText implementation, so the preview
matches what Sphinx produces for core reST. The Sphinx and Zephyr roles and
directives that plain docutils doesn't know are handled too, so Sphinx
project docs (such as Zephyr's README.rst files) look right instead of
showing error boxes.
Features
- Live preview that updates as you type and keeps its scroll position.
- Scroll sync in both directions; double-click in the preview to jump to
that line in the source.
- Previews are restored after VS Code restarts.
- Syntax highlighting with Pygments, coloured for light, dark and
high-contrast themes.
- Problems shown in place: real reST mistakes (bad indentation, short
title underlines, unknown targets) appear where they happen and are listed
under the document, so you can catch them before sending a docs change.
Sphinx and Zephyr support
| Construct |
Preview |
code-block, sourcecode, code (any Sphinx options) |
Highlighted; unknown lexers (e.g. kconfig) shown as plain text |
literalinclude with :lines:, :start-at:/:start-after:, :end-at:/:end-before:, :dedent:, :linenos: |
File included and highlighted |
:ref:, :doc:, :term:, :zephyr:code-sample: |
Link title (Title <target> → Title) |
:c:func:, :kconfig:option:, :dtcompatible:, any domain:role |
Symbol shown as code |
:kbd:, :guilabel:, :menuselection:, :file:, :samp: |
Styled inline |
:zephyr_file: / :zephyr_raw: |
Link to the file on GitHub |
zephyr:code-sample |
Header card with name, description and relevant API |
zephyr-app-commands |
Zephyr's own directive, loaded from the Zephyr tree the file is in (trusted workspaces only); a built-in approximation otherwise |
tabs / tab / group-tab |
Each tab shown in order with its label |
| Anything else unknown |
Content still rendered in a dashed box and listed under "Shown approximately" |
Usage
Open a .rst file, then use any of:
- the preview button in the editor title bar (Alt+click opens it in the same
column),
- right-click the editor tab, the editor, or the file in the Explorer,
- the Command Palette (
Ctrl+Shift+P): reStructuredText: Open Preview or
Open Preview to the Side,
Ctrl+Shift+V (preview) or Ctrl+K V (preview to the side).
| Command |
What it does |
| reStructuredText: Open Preview |
Preview in the current column |
| reStructuredText: Open Preview to the Side |
Preview next to the editor |
| reStructuredText: Show Source |
From a preview, go to its .rst file |
| reStructuredText: Refresh Preview |
Render the active preview again |
| reStructuredText: Restart Renderer |
Restart the Python renderer process |
| reStructuredText: Show Renderer Log |
Open the extension's output channel |
Settings
| Setting |
Default |
Description |
rstPreview.scrollSync |
true |
Keep the preview and the editor scrolled to the same place |
rstPreview.pythonPath |
"" |
A Python with docutils and Pygments; empty means the extension manages its own environment |
Requirements
Python 3.9 or newer on PATH. On first use the extension creates a private
virtual environment in its storage folder and installs the pinned docutils
and Pygments versions (one download from PyPI). Your project environments
are not touched. To use an interpreter of your own instead, set
rstPreview.pythonPath.
In untrusted workspaces the preview never runs code from the workspace.
Development
npm install
npm run compile
Press F5 in this folder to launch an Extension Development Host.
src/extension.ts: commands, preview panels, scroll sync, restoring
previews, the managed Python environment, and the renderer process (JSON
lines over stdio).
media/preview.js: the webview side: content updates, scroll mapping via
data-line markers, in-page links.
python/rst_render.py: docutils rendering, Sphinx/Zephyr roles and
directives, line markers, fallbacks.
python/audit.py <dir>: renders every README.rst under a folder and
reports fallbacks and warnings. On the Zephyr tree, 795 of 823 render with
no fallback or warning; the rest contain genuine reST errors, plus two
graphviz diagrams.
| |