如何使 sphinx-build 构建更快？答案

【问题标题】：How can I make sphinx-build build faster?如何使 sphinx-build 构建更快？
【发布时间】：2018-08-23 12:55:24
【问题描述】：

sphinx-build documentation 表示它只重建更改的文件。但在这个项目中，它正在为每个模块重建所有输出文件。 “突出模块代码”阶段需要特别长的时间。 Python 源文件根本没有改变，sphinx-apidoc 生成的 .rst 文件也没有改变——我只编辑了一些其他的 .rst 文件。

这个项目有 700 多个模块，所以 sphinx-build 大约需要 20 分钟，即使是 -j 8。我怎样才能让它更快？

我使用的命令是：

sphinx-build -M html source build

以及source/index.rst的相关部分：

.. toctree::
   :maxdepth: 1

   tutorial/index
   library/modules
   development/index
   setup/index
   usage/index
   test_cases/index
   services/index
   troubleshooting
   todo/index

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

我正在更改services 目录中的文件。

【问题讨论】：

sphinx-apidoc 不是 sphinx-build 选项或构建器。不要把两者等同起来。它们是两个不同的应用程序。也就是说，通常运行一次sphinx-apidoc，然后在模块更新时手动更新生成的 reST 文件。这将允许 Sphinx 缓存以前的构建并仅更新更改的文件。 20 分钟是一个非常长的时间，但对于 700 个模块（很多），也许不是。 700 个模块有自己的文档吗？如果是这样，那么使用 intersphinx。
Makefile 运行 sphinx-apidoc，但报告源文件没有更改并且不会为它们重新生成 .rst 文件。他们仍然有原来的时间戳。
你正在运行make_mode。我不明白它是如何调用sphinx-apidoc 的，因为它不是构建器。你说的对我来说没有意义。无论如何，我怀疑还有其他事情发生，比如clean，它删除了所有呈现的 HTML 和 Sphinx 的缓存文档树。也许试试make html？
在这一点上，如果没有可重复的示例，任何人都无能为力。新 Sphinx 项目中的构建不会满足您的体验。我建议从头开始创建一个新的 Sphinx 项目，然后向其中添加一些零碎的东西，测试每一点，直到你找到它的横向发展。
更改navigation_depth 并没有太大区别，但更改collapse_navigation 确实有效果- 不到三分钟！即使是最初的navigation_depth 4 也是如此。我已将问题的标题更改为使sphinx-build 更快，而不是专门针对增量构建，因此请将您的最后评论放入答案中，我会接受它，谢谢！

标签： python-sphinx

【解决方案1】：

尝试将navigation_depth theme option 从其默认值 4 更改为 2，并将 collapse_navigation 更改为 True。见注：

将 collapse_navigation 设置为 False 并使用较高的 navigation_depth 会导致具有许多文件和较深文件结构的项目生成的 HTML 文件的文件大小要大得多并且编译时间要长得多。"

【讨论】：

【解决方案2】：

我将以下属性添加到conf.py：

html_copy_source = False

使用此属性，Sphinx 不会将源文件复制到输出（默认情况下，它会将源文件复制到“_sources”）。

这并没有加快构建速度，但我有一个 SSD 驱动器。也许如果你有一个普通的，这个过程会更快，因为 Sphinx 必须复制更少的文件。

【讨论】：