当源文件更改时自动构建 Sphinx 文档

Question

我正在使用 Sphinx 来记录我的一个项目，并且我喜欢在浏览器中预览我的更改。我希望能够将一些更改保存到 .rst 文件中，并能够立即刷新浏览器并查看更改。

本质上，我想每当 .rst 文件之一发生更改时自动执行 make html 。

Answer 1

您可以使用 sphinx-autobuild。它还会自动在浏览器中启动页面刷新。

它很容易使用，例如：

sphinx-autobuild docs docs/_build/html

或者，如果您有一个单独的构建目录，

sphinx-autobuild <doc-source-dir> <doc-build-dir>

其中 是文档的源目录， 是您想要构建 html 文件的目录。

Answer 2

Jacob Kaplan-Moss 有一个很好的解决方案：

pip install watchdog
watchmedo shell-command \
          --patterns="*.rst" \
          --ignore-pattern='_build/*' \
          --recursive \
          --command='make html'

注意，更改模式以匹配您的后缀。 Jacob 使用 *.txt，但我需要将其更改为 *.rst。

Answer 3

如果您使用的是 *nix 系统，则可以使用 inotify 来监视文件系统事件并触发操作。

例如，在 ubuntu 上，

apt-get install inotify-tools

然后运行这样的脚本来侦听给定目录中的事件

while true
  do
    inotifywait -r -e modify -e move -e create -e delete /tmp/docs | while read line
      do
        echo "file changed; time to run make html"
      done
  done

Answer 4

您可以在您最喜欢的编辑器中创建一个宏来保存文件并在浏览器中打开它，任何文本编辑器都可以（geany、gedit、emacs、vi、notepad++...）

Answer 5

重建页面并在 VSCode 中刷新预览

如果使用 vscode，请安装 实时预览，带有 sphinx-build 和 restructedText 然后，在 zsh 终端中，从您的文档根目录，使用单个命令，您可以：

• 重建 (make html），
• 打开预览 build/html/doc.html
• 重新打开您正在编辑的文档 code -r source/doc.rst

make html && code -r build/html/doc.html && code -r source/doc.rst

• make html 将构建文档树
• code -r 将在两种情况下重用当前窗口

如果每个 doc.html，实时预览 的 doc.html 和 doc.rst 均已打开，sphinx 将重建树，vscode 将打开刷新的预览，然后返回编辑状态doc.rst。

更进一步

，创建一个动态键绑定，它将使用任何打开的 .rst 文件的键盘快捷键来完成上述所有操作。将其添加到您的 keybindings.json 中：

   {
      "key": "cmd+shift+R",
      "command": "workbench.action.terminal.sendSequence",
      "args": {
        "text": "VSCODEOPENFILE=${file} && sphinx-build -M html ${VSCODEOPENFILE:h} ${${VSCODEOPENFILE:h}/source/build/} ${VSCODEOPENFILE} && code -r ${${VSCODEOPENFILE:h}/source/build/}${${VSCODEOPENFILE:t}/rst/html} && code -r ${VSCODEOPENFILE}\u000D"
      },
      "when": "textInputFocus && !editorReadonly"
    }

• "key": "cmd+shift+R" 是键盘快捷键。当您的 rst 文件位于活动编辑器中时运行此命令
• "command": "workbench.action.terminal.sendSequence" 告诉 vscode 要执行的操作（将 args 作为命令运行在终端中）
• "args": { "text" : 中的命令
  • VSCODEOPENFILE=${file} 将环境变量设置为当前打开的文件路径
  • sphinx-build -M html ${VSCODEOPENFILE:h} ${${VSCODEOPENFILE:h}/source/build/} ${VSCODEOPENFILE} && code -r ${${VSCODEOPENFILE:h}/source/build/}${${VSCODEOPENFILE:t}/rst/html} 将仅在当前文件上运行 sphinx 重建
    • -M html 使用 html 构建器
    • ${VSCODEOPENFILE:h} 是 source 目录的路径，例如 workspace/docs/source
    • ${${VSCODEOPENFILE:h}/source/build/} 将 build 替换为 source 以获取构建目录的路径，例如，workspace/docs/build
    • code -r ${${VSCODEOPENFILE:h}/source/build/}${${VSCODEOPENFILE:t}/rst/html} 将替换 build 对于 source 和 html 对于参数中的 rst （即 source/doc.rst 将变为 build/doc.html,) 并在现有窗口中重新打开它，强制刷新实时预览
    • code -r ${VSCODEOPENFILE} 将返回到原始窗口（例如，doc.rst）进行编辑。
• when 设置将限制 Command-Shift-R 命令仅在编辑器处于焦点状态且非只读时才起作用。

注意此代码适用于 mac os x 和 zsh，但可能会在其他地方进行一些调整，

这解决了我通过 sphinx-autobuild 进行连续自动重建的问题 我认为是由于 conf.py 中的 shutil.copyfile 造成的。我还尝试了一些 vscode sphinx 和 rst-preview 扩展，但它们都不起作用。