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

Question

我正在使用 Sphinx 来记录我的一个项目，并且我喜欢在浏览器中预览我的更改。我希望能够将一些更改保存到

.rst

文件，并能够立即刷新我的浏览器并查看更改。

本质上，我想每当

make html

文件之一发生更改时自动执行

.rst

。

Answer 1

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

使用起来很方便，例如：

sphinx-autobuild docs docs/_build/html

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

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

其中

<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 安装 Live Preview，然后在

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

  命令仅在编辑器聚焦且非只读时才起作用。

注意

此代码适用于 mac os x 和 Command-Shift-R，但稍作调整即可在其他地方使用

这解决了我通过

zsh

进行连续自动重建的问题，我认为是由于

sphinx-autobuild

中的

shutil.copyfile

。我还尝试了一些 vscode sphinx 和 rst-preview 扩展，但它们都不起作用。