vscode 正确处理 rst 需 python 环境、docutils/sphinx 依赖、插件配置三者协同；缺 docutils 则预览空白，需 pip install docutils；用 sphinx 高级功能须装 sphinx 及主题；须确认 python 解释器一致、语言模式设为 restructuredtext、启用补全设置；预览默认简陋，应右键选“preview with sphinx”并配 conf.py 和 html_theme。

VSCode 要能正确编写、预览和校验 RST 文档，光装一个插件远远不够——必须同时满足 Python 环境、docutils/sphinx 依赖、插件配置三者协同，缺一不可。

reStructuredText 插件装了但预览空白或报错 ModuleNotFoundError: No module named 'docutils'

这是最常卡住的第一步。插件本身不带解析器，完全依赖你本地 Python 环境里的 docutils（基础解析）或 sphinx（增强渲染）。VSCode 不会自动帮你装这些包。

• 在终端执行 pip install docutils —— 预览基础 RST 必须有它
• 如果要用 Sphinx 主题（比如 sphinx_rtd_theme）、支持 :ref:、:toctree: 等高级指令，还得额外装 sphinx：pip install sphinx sphinx_rtd_theme
• 确认 VSCode 正在用的 Python 解释器和你运行 pip 的是同一个：按 Ctrl+Shift+P → 输入 Python: Select Interpreter，选中你刚装包的那个环境（比如 venv/bin/python）
• 插件设置里检查 restructuredtext.confPath 是否指向含 conf.py 的目录（若用 Sphinx）；否则留空即可走 docutils 默认路径

输入 .. code-block:: python 没自动补全或高亮失效

RST 语法补全和高亮不是开箱即用的，需要插件 + 语言模式双重激活。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• 确保已安装 reStructuredText 插件（作者 lextm），且重启过 VSCode
• 打开任意 .rst 文件，右下角状态栏检查语言模式是否为 reStructuredText；如果不是，点击它 → 选择 Configure File Association for '.rst' → 设为 reStructuredText
• 部分补全（如 .. note::、.. versionadded::）需在行首输入 .. 后触发；code-block 类指令通常要输入完整前缀再按 Tab
• 若仍无响应，检查设置中是否禁用了建议：editor.suggest.showSnippets 和 editor.quickSuggestions 都应设为 true

预览窗口不随编辑实时刷新，或样式丑得像纯文本

默认预览走的是 docutils 的简易 HTML 渲染，没 CSS、没主题、不支持自定义样式。想接近 Sphinx 输出效果，得主动切换到 Sphinx 模式。

• 在 .rst 文件内右键 → 选择 reStructuredText: Preview with Sphinx（不是普通 Preview）
• 该命令要求当前工作区根目录或 source/ 目录下存在 conf.py；没有就运行 sphinx-quickstart 初始化一次
• 预览首次加载慢是正常的（Sphinx 初始化开销），但后续保存应 1–2 秒内刷新；若延迟过高，检查 conf.py 中是否误配了耗时扩展（如 sphinx.ext.autodoc 在无代码时也启用）
• 样式难看？在 conf.py 里加一行：html_theme = 'sphinx_rtd_theme'，并确保已 pip install sphinx_rtd_theme

最容易被忽略的是：VSCode 的 RST 预览不读取你项目里 Makefile 或 build/ 目录的输出，它每次都是临时生成——所以别指望它显示你 make html 后的最终效果，它只是开发过程中的快速参考。真要验证最终排版，还是得跑一遍 make html 打开 _build/html/index.html。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！