vscode预览restructuredtext需手动安装sphinx/docutils、正确配置python解释器并选择“preview with sphinx”模式，三者缺一不可；否则将出现空白页或modulenotfounderror错误。

VSCode 本身不带 Sphinx，必须手动装依赖、配解释器、选对预览模式，三者缺一不可——否则点预览只会看到空白页或 ModuleNotFoundError: No module named 'docutils'。

装 Sphinx 和 docutils 必须用 pip，不能只靠插件

reStructuredText 插件（lextm 版）只是个壳，所有解析工作都交给本地 Python 环境里的 docutils（基础渲染）或 sphinx（主题/指令支持）。VSCode 不会自动帮你装包。

• 基础预览：运行 pip install docutils
• 要支持 :ref:、:toctree:、Sphinx 主题（如 sphinx_rtd_theme）：再运行 pip install sphinx sphinx_rtd_theme
• 如果你在虚拟环境中开发，确保 pip 和 VSCode 用的是同一个环境——比如 venv/bin/python 或 Scripts/python.exe

VSCode 必须选对 Python 解释器，且语言模式设为 reStructuredText

即使包装好了，VSCode 仍可能调用错解释器，导致预览失败。常见现象是右键“Preview”没反应，或报错找不到模块。

Sakura python draw

使用Python的turtle和random库，递归绘制分形樱花树，并动画模拟花瓣自然飘落效果。

下载

• 按 Ctrl+Shift+P → 输入 Python: Select Interpreter → 选中你刚用 pip 装包的那个 Python（注意看路径，别选系统 Python 或 conda base）
• 打开任意 .rst 文件，看右下角状态栏：语言模式必须是 reStructuredText；如果不是，点击它 → Configure File Association for '.rst' → 设为 reStructuredText
• 插件设置里检查 restructuredtext.confPath：若项目有 conf.py，就填它所在目录；没有就留空，走 docutils 默认路径

预览必须右键选 “Preview with Sphinx”，不是普通 Preview

默认的 Preview 按钮走的是 docutils 的极简 HTML 渲染，没 CSS、不识别 Sphinx 指令、样式像纯文本。想看到真实效果，得主动切过去。

• 在 .rst 文件编辑区右键 → 找到 reStructuredText: Preview with Sphinx（注意名字里带 Sphinx）
• 首次使用会尝试读取项目根目录或 source/ 下的 conf.py；如果没找到，会 fallback 到 docutils，但不会报错，只会显示简陋结果
• 预览窗口不自动刷新，需手动 Ctrl+S 保存文件后才会更新

conf.py 和 index.rst 是 Sphinx 项目的最小骨架

没有 conf.py，Sphinx 预览无法加载主题、扩展和路径配置；没有 index.rst，连首页都打不开。它们不是可选项，是启动前提。

• 快速生成：在项目根目录终端运行 sphinx-quickstart，按提示选 source/ 目录、是否分拆 build/，其余全默认即可
• conf.py 至少要确认这几项：extensions = ['sphinx.ext.autodoc']（如需 API 文档）、html_theme = 'sphinx_rtd_theme'（主题）、source_suffix = '.rst'
• index.rst 开头必须有 .. toctree:: 指令，否则子页面不会被索引；哪怕只写一行 :maxdepth: 1 也比空着强

最容易被忽略的是解释器一致性——你用 pip3 install sphinx 装的包，VSCode 却在用 /usr/bin/python 启动预览，这种错位不会报错，只会静默失败。每次换环境（比如新建 venv、切 conda env），都要重新确认解释器和 pip 是否指向同一位置。

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