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

Question

我正在使用Sphinx来为我的一个项目写文档，我希望能在浏览器中预览我的修改。我想在一个.rst文件中保存一些更改，然后能够立即刷新浏览器，看到这些更改。

简单来说，我想要在每次修改.rst文件时，自动执行一次make html命令。

Answer 1

如果你在一个 *nix 系统上，比如 Linux，你可以使用 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 2

Jacob Kaplan-Moss 提供了一个不错的解决方案：

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

注意，要根据你的文件后缀来修改这个模式。Jacob 使用的是 *.txt，但我需要把它改成 *.rst。

Answer 3

你可以使用 sphinx-autobuild。这个工具会自动在浏览器中刷新页面。

使用起来很简单，比如：

sphinx-autobuild docs docs/_build/html

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

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

这里的 <doc-source-dir> 是你文档的源目录，而 <doc-build-dir> 是你想要存放生成的html文件的目录。