Sphinx-Autobuild 使用指南

Sphinx-Autobuild 使用指南

sphinx-autobuild Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server. 项目地址: https://gitcode.com/gh_mirrors/sp/sphinx-autobuild

1. 项目介绍

Sphinx-Autobuild 是一个用于自动重建 Sphinx 文档的工具，当检测到文档目录中的更改时，它会自动重新构建文档，并包含一个热重载的 Web 服务器。这使得在开发文档时可以实时查看更改效果，极大地提高了文档编写和调试的效率。

Sphinx-Autobuild 是基于 Sphinx 文档生成器的扩展，适用于需要频繁更新和预览文档的场景，如技术文档编写、API 文档生成等。

2. 项目快速启动

安装

Sphinx-Autobuild 可以通过 pip 安装：

pip install sphinx-autobuild

使用

要使用 Sphinx-Autobuild 构建一个经典的 Sphinx 文档集，可以运行以下命令：

sphinx-autobuild docs docs/_build/html

这将启动一个服务器，默认地址为 http://127.0.0.1:8000，并开始监视 docs/ 目录中的更改。当检测到更改时，文档会自动重新构建，并且任何打开的浏览器窗口都会自动刷新。

要停止服务器，可以使用 Ctrl + C。

命令行选项

Sphinx-Autobuild 接受与 sphinx-build 相同的参数，并且还有一些额外的选项，可以通过运行 sphinx-autobuild --help 查看：

sphinx-autobuild --help

3. 应用案例和最佳实践

案例1：开发 Sphinx HTML 主题

在开发 Sphinx HTML 主题时，可以将主题的源目录添加为监视目录。建议禁用 Sphinx 的增量构建，以确保所有页面都从相同的 HTML 主题状态构建。

sphinx-autobuild -a docs docs/_build/html --watch path/to/theme

案例2：同时开发多个项目

在同时开发多个 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 magikarp/docs/_build/html &

4. 典型生态项目

Sphinx

Sphinx 是一个用于生成文档的工具，支持多种输出格式，如 HTML、LaTeX、ePub 等。它是 Sphinx-Autobuild 的基础，提供了文档生成和构建的核心功能。

Read the Docs

Read the Docs 是一个在线文档托管服务，支持自动构建和托管 Sphinx 文档。它与 Sphinx-Autobuild 结合使用，可以实现文档的自动构建和发布。

Jupyter Book

Jupyter Book 是一个基于 Sphinx 的项目，用于创建交互式书籍和文档。它支持 Markdown 和 Jupyter Notebook 文件，并提供了丰富的插件和主题。

通过这些生态项目，Sphinx-Autobuild 可以与其他工具无缝集成，提供更强大的文档编写和发布功能。

sphinx-autobuild Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server. 项目地址: https://gitcode.com/gh_mirrors/sp/sphinx-autobuild