7. 在Visual Studio Code中使用¶

Visual Studio Code是一款非常好用的免费编辑器, 可以在Windows, Mac, Linux多平台使用. 借助于vscode扩展, 我们也可以在vscode中编译预览reST文档.

7.1. 安装步骤¶

参考: https://github.com/vscode-restructuredtext/vscode-restructuredtext/blob/master/docs/sphinx.md

安装Python (2.7.10+)
安装pip.

假设python安装在C:\Python27, 进入其中的Scripts目录, 运行 easy_install pip
安装sphinx

pip install sphinx sphinx-autobuild
安装restructuredtext-lint

pip install restructuredtext-lint
安装reStructuredText插件, 作者LeXtudio

可以在vscode中安装或者到 https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext安装

7.2. 配置¶

全局配置

依次打开菜单: 文件/首选项/设置, 加入:

# windows
"restructuredtext.linter.executablePath": "C:\\Python27\\Scripts\\restructuredtext-lint.exe"
# Mac/Linux, 应该是默认值，不用设置
"restructuredtext.linter.executablePath": "restructuredtext-lint"

当前文件夹配置

Windows

假设项目文件夹为D:\dev\hds, 且reST文档源文件位于D:\dev\hds\doc, conf.py也在这个目录下, 在D:\dev\hds\.vscode\settings.json中加入以下配置:

"restructuredtext.builtDocumentationPath" : "${workspaceRoot}/doc/_build/html",
"restructuredtext.confPath"               : "${workspaceRoot}/doc",
"restructuredtext.updateOnTextChanged"    : "true",
"restructuredtext.sphinxBuildPath"        : "C:\\Python27\\Scripts\\sphinx-build.exe"

Mac

假设项目文件夹为/Users/zzq/dev/hds, 且reST文档源文件位于/Users/zzq/dev/hds/doc, conf.py也在这个目录下, /Users/zzq/dev/hds/.vscode/settings.json中加入以下配置:

"restructuredtext.builtDocumentationPath" : "${workspaceRoot}/doc/_build/html",
"restructuredtext.confPath"               : "${workspaceRoot}/doc",
"restructuredtext.updateOnTextChanged"    : "true"

sphinx-build路径不用设置，用默认值即可.

7.3. 使用¶

Windows:

在vscode中打开reST文件, 按下 Ctrl+Shift+R 组合键, 稍等几秒, 即可打开该文件的HTML预览.

Mac:

在vscode中打开reST文件, 按下 Command+Shift+R 组合键, 稍等几秒, 即可打开该文件的HTML预览.

7.4. 问题记录¶

7.4.1. reStructuredText插件40.0.0版本bug¶

此版本存在bug, 会使reST文档目录与项目文件夹根目录不同时无法预览, 我已在github提交issue: https://github.com/vscode-restructuredtext/vscode-restructuredtext/issues/69 并自己编译了一个版本修正了这个bug.

reStructuredText插件编译步骤(Linux):

cd ~
git clone https://github.com/vscode-restructuredtext/vscode-restructuredtext.git
cd ~/vscode-restructuredtext
npm install --unsafe-perm=true
npm install vscode
npm install thenable
npm run compile

编译完成后, 将整个rscode-restructuredtext目录拷贝到vscode插件目录即可, 不同操作系统这个目录不同:

Windows %USERPROFILE%\.vscode\extensions
Mac $HOME/.vscode/extensions
Linux $HOME/.vscode/extensions

也可以打包成vsix文件然后安装:

npm install -g vsce
vsce package

但我打包好的vsix在windows 10上安装失败, 我怀疑是没有经过签名所以被拒绝.