sphinx-autobuild

7.1. sphinx-autobuild#

在文档编写过程以及功能、样式修改过程，可能需要频繁变动指令和查看结果。 虽然 VS Code 支持 MyST 语法高亮，但是不支持对应的 .md 文件的预览功能， 但是需要主动构建html文件或者通过预览 rst 文件来更新 md 文件的本地html构建结果，效率十分差； 为此，我们可以使用 sphinx-autobuild 工具 ， 它能够支持在浏览器中实时重新加载有关更改的 Sphinx 文档。

关于此项目的更多信息或建议前往 executablebooks/sphinx-autobuild 查看。

7.1.1. 安装#

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

pip install sphinx-autobuild

7.1.2. 用法#

要构建经典的 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

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

代码 7.1.1 .sh 批处理#
#!/bin/sh
sphinx-autobuild source source/_build/html --open-browser --port=0
代码 7.1.2 .bat 批处理#
sphinx-autobuild source source/_build/html --open-browser --port=0

7.1.3. 命令行选项#

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

7.1.4. 自动打开浏览器#

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

7.1.5. 自动选择端口#

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

目录