sphinx-autobuild¶

需要注意的是，sphinx-copybutton 插件对文档索引的更新没办法做到动态更新，所以如果在对项目文档的目录修改后，会出现不同页面的左侧边栏目录不同的情况。

在浏览器中实时重新加载有关更改的 Sphinx 文档。关于此项目的更多信息或建议前往 executablebooks/sphinx-autobuild 查看。

安装¶

sphinx-autobuild 在 PyPI 上可用。它可以使用 pip 安装：

pip install sphinx-autobuild

用法¶

要构建经典的 Sphinx 文档集，请运行：

sphinx-autobuild source source/_build/html

这将在 http://127.0.0.1:8000 启动服务器并开始监视 source/ 目录中的更改。当在 source/ 中检测到更改时，将重建文档并自动重新加载任何打开的浏览器窗口，而结果则输出在 source/_build/html 中。

使用 KeyboardInterrupt( ctrl+ c) 停止服务器。

推荐用法

sphinx-autobuild source source/_build/html --open-browser --port=0

当然，可以将其写入批处理文件中，这样就可以直接执行：

代码块 1 .sh 批处理¶

#!/bin/sh
sphinx-autobuild source source/_build/html --open-browser --port=0

代码块 2 .bat 批处理¶

sphinx-autobuild source source/_build/html --open-browser --port=0

命令行选项¶

sphinx-autobuild 接受与 sphinx-build（这些在每次构建时传递给 sphinx-build ）相同的参数。它还有一些额外的选项，可以通过运行看到 sphinx-autobuild --help

$ sphinx-autobuild --help
usage: sphinx-autobuild [-h] [--port PORT] [--host HOST] [--re-ignore RE_IGNORE] [--ignore IGNORE] [--no-initial] [--open-browser]
                        [--delay DELAY] [--watch DIR] [--pre-build COMMAND] [--version]
                        sourcedir outdir [filenames [filenames ...]]

positional arguments:
  sourcedir             source directory
  outdir                output directory for built documentation
  filenames             specific files to rebuild on each run (default: None)

optional arguments:
  -h, --help            show this help message and exit
  --port PORT           port to serve documentation on. 0 means find and use a free port (default: 8000)
  --host HOST           hostname to serve documentation on (default: 127.0.0.1)
  --re-ignore RE_IGNORE
                        regular expression for files to ignore, when watching for changes (default: [])
  --ignore IGNORE       glob expression for files to ignore, when watching for changes (default: [])
  --no-initial          skip the initial build (default: False)
  --open-browser        open the browser after building documentation (default: False)
  --delay DELAY         how long to wait before opening the browser (default: 5)
  --watch DIR           additional directories to watch (default: [])
  --pre-build COMMAND   additional command(s) to run prior to building the documentation (default: [])
  --version             show program's version number and exit

sphinx's arguments:
  The following arguments are forwarded as-is to Sphinx. Please look at `sphinx --help` for more information.
    -b=builder, -a, -E, -d=path, -j=N, -c=path, -C, -D=setting=value, -t=tag, -A=name=value, -n, -v, -q, -Q, -w=file, -W, -T, -N, -P

自动打开浏览器¶

sphinx-autobuild 可以在默认浏览器中打开生成文档的主页。通过 --open-browser 将启用此行为。

自动选择端口¶

sphinx-autobuild 要求操作系统提供一个空闲端口号并将其用于其服务器。通过 --port=0 将启用此行为。