在浏览器中实时重新构建Sphinx文档，以响应更改。
项目描述
在浏览器中实时重新构建Sphinx文档，以响应更改。
安装
sphinx-autobuild 可在 PyPI 上找到。可以使用 pip 进行安装
pip install sphinx-autobuild使用方法
要构建传统的 Sphinx 文档集，请运行
sphinx-autobuild docs docs/_build/html这将启动一个服务器在 http://127.0.0.1:8000 并监视 docs/ 目录中的更改。当检测到 docs/ 目录中的更改时，文档将被重新构建，并且任何打开的浏览器窗口将自动重新加载。通过 KeyboardInterrupt (ctrl + c) 可以停止服务器。
命令行选项
sphinx-autobuild 接受与 sphinx-build 相同的参数（这些参数在每个构建过程中传递给 sphinx-build）。它还有一些额外的选项，可以通过运行 sphinx-autobuild --help 来查看。
$ sphinx-autobuild --help
usage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
...
autobuild options:
--port PORT port to serve documentation on. 0 means find and use a free port
--host HOST hostname to serve documentation on
--re-ignore RE_IGNORE
regular expression for files to ignore, when watching for changes
--ignore IGNORE glob expression for files to ignore, when watching for changes
--no-initial skip the initial build
--open-browser open the browser after building documentation
--delay DELAY how long to wait before opening the browser
--watch DIR additional directories to watch
--pre-build COMMAND additional command(s) to run prior to building the documentation与 Makefile 一起使用
注意：Sphinx 正计划 放弃使用 Makefile。
要使用 Sphinx 生成的 Makefile 与 sphinx-autobuild 一起使用，请在 Makefile 的末尾添加以下内容
livehtml:
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)make livehtml 现在将调用 sphinx-autobuild。
如果您使用的是较旧的 Sphinx 版本生成的 Makefile，则此语法可能对您不起作用。请考虑 更新到较新的结构。
自动打开浏览器
sphinx-autobuild 可以在默认浏览器中打开生成的文档的主页。通过传递 --open-browser 将启用此行为。
自动选择端口
sphinx-autobuild 会向操作系统请求一个空闲端口号，并使用该端口号作为其服务器。通过传递 --port=0 将启用此行为。
工作流程建议
在 Sphinx HTML 主题上工作
当在 Sphinx HTML 主题上工作时，请将主题的源目录添加为监视目录。还建议通过将 -a 选项传递给 sphinx-autobuild 来禁用 Sphinx 的增量构建。
sphinx-autobuild -a docs docs/_build/html --watch path/to/theme这会导致构建速度变慢，但可以确保所有页面都是从相同的 HTML 主题状态构建的。它还解决了 Sphinx 中已知的问题，这在主题开发期间可能导致重大问题。
在多个项目中工作
当同时处理多个 Sphinx 文档项目时，需要为每个项目使用不同的输出目录。还建议使用 --port=0 和 --open-browser 以避免手动管理端口和打开浏览器窗口（这很快就会变得繁琐）。
sphinx-autobuild --port=0 --open-browser pikachu/docs pikachu/docs/_build/html &
sphinx-autobuild --port=0 --open-browser magikarp/docs magickarp/docs/_build/html &相关 Sphinx Bug
Sphinx 在增量模式下不 检测非文档、非代码文件中的更改，如主题文件和静态文件。
在编写本文时，唯一的已知解决方案是指导 Sphinx 重新构建相关页面。这可以通过禁用增量模式（使用 -a）或在 CLI 中除源目录和输出目录外还传递相关 filenames 来完成。
致谢
该项目得益于巨人的肩膀，没有他们，这个项目将无法实现。
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
源代码分发
构建分发
哈希值 for sphinx_autobuild-2024.10.3-py3-none-any.whl
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 158e16c36f9d633e613c9aaf81c19b0fc458ca78b112533b20dafcda430d60fa |
|
| MD5 | 502227db5aa60ca942a2b84bc32ac5c1 |
|
| BLAKE2b-256 | 18c0eba125db38c84d3c74717008fd3cb5000b68cd7e2cbafd1349c6a38c3d3b |