Sphinx 使用与定制

Jupyter Book 使用 Sphinx 文档引擎 从您的源文件构建丰富的文档模型。 这也允许在底层进行一些额外的定制。 本章介绍了几种定制 Sphinx 或直接使用它来构建书籍的方法。

Caution

手动定制 Sphinx 被视为高级用法——强烈建议您阅读 Sphinx 文档。

将您的 Jupyter Book 转换为 Sphinx 网站

可以将 Jupyter Book 转换 为与 Sphinx 直接兼容的结构。 这使您可以直接使用 Sphinx 命令（如 sphinx-build）构建书籍。 如果您希望使用直接支持 Sphinx 构建的服务，如 ReadTheDocs，或者希望使用 Sphinx 特定的命令（如 sphinx-autobuild），这将非常有用。

Sphinx 构建 Jupyter Book 所需的唯一文件是 conf.py。 要从您的书籍的 _config.yml 文件生成一个，请运行以下命令：

jupyter-book config sphinx path/to/book

See also

参见 命令行界面参考 以获取此命令的更多使用信息。

这将使用您的 _config.yml 文件和您的 _toc.yml 文件生成适当的 conf.py。 完成后，您可以使用标准的 Sphinx 构建命令构建您的书籍。 例如：

sphinx-build path/to/book path/to/book/_build/html -b html

Warning

不要手动编辑您的 conf.py 文件。 相反，更新您的 _config.yml 文件并重新运行 jupyter-book config sphinx，以确保这两个配置文件保持同步。